Writing code has a part which I think many developers do not focus so much on: Documentation.
Installation – what I did
I am on OS X, and it was relative easy to get started with. There however is a part of Docker which requires Python, that called for som googling but I succeed following these steps:
- If you dont have Node.js, you need to install node.js.
- Install docker in node.js:
sudo npm install -g docker
- You need to install Python
- You need to install pip, which is I guess a sort of package manager for Python.
sudo easy_install pip
- You need to install Pygments which, as I understand it will be the part prettifying the code in the generated documentation.
sudo pip install Pygments
After that you are ready to start generating documentation for your code!
Your first documentation
You now have Docker.js which will generate a folder containing documentation of the files you specified.
As it is based on node.js you open up a terminal:
You can open terminal simply by pressing Cmd+Space and enter “Terminal” + Enter
From terminal you have access to fire up Node.js. But first navigate to a folder where your source code is. You can use
I use to type “cd ” and then using Finder I find the folder and then drag the folder to the Terminal. That way terminal will paste the path to the folder into the command line.
We are ready to generate documentation. Docker can take a lot of options, but for now lets just try the basic command, asking it to only document one file.
By default Docker will create a folder called “Doc”, that you of cause can change using the Docker options.
In my case Docker created this:
Now you simply need to open the html file generated, in my case “fodbold.js.html”:
The output – the documentation
As you can see above the documentation is divided into 3 main sections:
- Comments to the code
- The code
If you run it on your raw code you will not get those comments, and documentation of how to call a function, but wait that part is also easy!
I use Adobe Brackets free editor for coding, and it just happens that there exist (at least) an Extension which can ease the process adding comments to your code.
I use FuncDocr which will prefix your functions through one menu click. You dont see the JSDoc (which FuncDocr adds) in my documentation, as Docker removes them and adds them to the comment section.
Here is an example of the raw JSDoc from my “fodbold.js” file:
The hardest part of documenting
So I guess the hardest part remains to be the actual adding of notes! But no software can help you with that!
The path to a better documentation has been advised here now, so pull yourself together and start documentation.
I for one will try (I promise!) to start doing it.. :–)
It looks like you can even add Docker to your Grunt scripts.