search

libgit2 / node-gitteh

Node.js bindings for libgit2
http://libgit2.github.com
MIT License
431 stars 56 forks source link

Proper Documentation #11

Closed samcday closed 13 years ago

samcday commented 13 years ago

Gitteh needs some proper documentation.

Given that the bindings are wholly implemented in C++ land, I'm loathe to try and get some weird doxygen setup or something to work and document the JS exposed bindings.

I think the best bet is to create a set of Javascript dummy files that correlate to the functionality offered in C++ land, then I can just attach empty functions to prototypes, document them, and run a documentation tool on that.

TooTallNate commented 13 years ago

I think that for some of these other idea's you've been talking about (like implementing revParse in JS land), you going to have to change the main in the package.json to point to a regular JS entry file at some point (soon), that also exposes the native bindings as needed (or convenience wrappers around the native binding).

It makes it a lot easier to verify arguments in JS land before passing to the native binding. Also, you'd be able to add documentation to the JS file there. Also, I'm much more comfortable in JS, so once an entry file is in place, I'll be likely sending pull requests your way to implement some of this functionality if I can.

samcday commented 13 years ago

I'm not really sure if this is feasible at this point. I built gitteh from the ground up to be quite integral in C++ land. There is alot more going on than you'd think when it comes to working with gitteh. I don't think I could just expose gitteh stuff as low level binding methods (maybe I could have done this from the ground up, but I didn't, so).

I think I'd like to keep the bindings the way they are, and keep them exposed to the user, again the way they are (pure C++ implemented bindings).

However any functionality built on top of gitteh low level bindings, let's call the low level stuff the "plumbing" framework, I think should be done in a high level JS module. Probably the best way to do this is change the main entry point to a JS module. From this module we export the gitteh.node native stuff, and then build on top of it via new classes.

Also, I exposed the constructors for everything in the latest commits. You can't use the constructors directly, but now you can manipulate the prototypes.

If you were interested in kicking this process off, or being involved, I would definitely appreciate that. Are you in the Node IRC channel? Might be easier to talk properly there :)

samcday commented 13 years ago

Documentation is now up @ http://libgit2.github.com/node-gitteh/docs

Get it in ya!