Saturday, September 21, 2013

It's been a hell of a week on our current development with Sencha EXTJs. So too calm me down, I started reading and reading again and this is where I bumped with JSDuck.

JSDuck is Sencha's very own documenting framework, and I think they did a very good job on this one.

Before everything else, why document?

I really don't have any plans or any user story of having a documentation from our development roadmap and when I found JSDuck and its awesomeness, for sure there will be a one or two user story that will focus on code documentation.

And to answer my own question:

  • If you can document your work then your are doing a good job
  • If you can detail every part of your class properties and methods then you really know what is really happening inside out
  • If you document, you will find that some of your code is good or bad. Then you can start having some todos and refactor your work.
  • New people on your project can easily start on your development team with your documentation

So why use JSDuck?

Let me first show you a common page from Sencha Extjs documentation.


You can check the live example here: Ext.Ajax documentation

If you wonder how can you make this kind of documentation well it is very easy. If you have been doing this stuff in your development: 

/**
* @class TestClass
* This is a test class only
* @property String A property string
* @author Ronald Allan Mojica
**/

Then the rest is easy.

Here is the list of things that I think why JSDuck rocks:

  • Cool interface
  • Built-in search engine all over your code
  • Easy to use with your current comment tags if you have it already
  • Cool sets of new tags like @example @video and @markdown
With JSDuck, it will provide you intuitive controls all over your code with the comment section you made with your code base.

Let's get started 

First let's get JSduck in your system, since JSDuck is Ruby gem you need to have at least the latest Ruby on your system, if not then install Ruby first and key in the following command:

$ sudo gem install jsduck

And then next step is to locate your code and let's start using JSDuck.

In your root folder of your application , start documenting with the following code:

$ jsduck [class folder] --output docs --title [Your App Name]

The output option is where your documentation will be generated and the title option is for your documentation title.

And that's it! After that you can open the index.html inside docs/ folder with your browser.

JSDuck references

For more information about JSDuck you can check out their official wiki which has lots of informative details on various comments syntax. Click here.

Example.js from SenchaLabs

At first I really don't know what syntax to use to generate a more informative Class documentation but this example.js from SenchaLabs really help. It has lots of samples regarding property, markdown and a lot more.