Stop documenting code in Wiki's. An essay on code documentation... using #Groc to generate documentation #js #javascript #nodejs

Oscar Brito



Every place I worked so far had the utopia of creating code documentation on internal wiki's. I always felt this not to be a natural process because we always end up having wrong and deprecated documentation. The reason was always that the developer tend to forget to open the wiki, search, and edit the content he wants ( very bureaucratic process! ) after he coded...

Another thing that always concerned me was the wiki attachments with UML diagrams, wireframes documents, ..., This never made sense! and continues not to make...

My thoughts on this subject are:

  1. Why not to save documents on a docs/ folder under the GIT/SVN repo? This way we have version control and the docs live near the implementation.

    This is similar to the polite README.md file's on github...

  2. Use literate programming on you coding and then generate API documentation for your modules/apps (like JSDocs, YUIDocs, etc...).

On my personal projects I'm using Groc to generate API documentation.

Let me tell you a little more about Groc now. Groc generate HTML page's where you can see your code comments and the related source code. This way you can always check the API and the implementation  (this is awesome!).

Groc uses markdown format and integrates easily with github (gp-pages branch).

To install Groc:



npm install groc -g

Create a file .groc.json on the project directory, like:



{
"glob": ["README.md", "src/*.js"],
"github": false,
"out": "doc/"
}

On your source files methods use literate programming, like:



/**
* ## doStuff()
* Do some programmatic stuff!
*
* @param {String} stuffName The name of the stuff to do
* @return {String} The stuff output
*/
function doStuff(stuffName){
return "done";
}

Now run groc to generate the docs/ of the project, on the project directory.


If you for some reason disagree with me on some point I would love to hear about that...

/Oscar Brito




Visit www.divhide.com for more informations, contacts and news about Web Development.
See other blog posts at blog.divhide.com.



Divhide purpose is to follow the HTML5 movement and contribute with applications which prove the quality of technology.


Feel free to contact divhide.