Writing documentation

If you are writing open source documentation, this is not just a polite addition to projects, it helps your project to a certain extent to take off. A well-written README helps, but full API documentation makes the project more professional. Even if your project is closed source, documentation will help new colleagues adapt more quickly or help you remember how things work in long-term projects.

Let's see how the documentation works in popular JavaScript frameworks.

jQuery

')
The jQuery documentation is located at docs.jquery.com and is a wiki that describes all the API documentation. Any large API area is included in the navigation, each page has a list of methods for this area. The page contains code examples and comments on Disqus.
Source code comments are mainly related to bugs or to an unusual piece of code that needs explanation.

Next: Prototype, JSDoc, and a few specific approaches to JavaScript documentation

Prototype

Prototype documentation is available at api.prototypejs.org . It is generated using pdoc . PDoc is:

... an inline comment parser and a JavaScript documentation generator written in Ruby. It is designed for Prototype documentation and libraries written in Prototype.

Prototype comments are markdown codes that can be converted by pdocs into documentation.
For an example, take a look at github.com/sstephenson/prototype/blob/master/src/prototype/ajax.js
/**
* == Ajax ==
*
* Prototype's APIs around the `XmlHttpRequest` object.
*
* The Prototype framework enables you to deal with Ajax calls in a manner that
* is both easy and compatible with all modern browsers.
*
* Actual requests are made by creating instances of [[Ajax.Request]].
*/
Unlike jQuery, the Prototype documentation is inside the source code.

Jsdoc

JSDoc is also a way to write inline documentation. Comments can begin with the special character @ for presentation of metadata:
/**
* Example constructor.
*
* @constructor
* @this {Example}
*/
Full HTML documentation can be generated using the jsdoc-toolkit . Also javascript projects with inline JSDoc can use dox to generate HTML documentation.

Docco

Docco is a documentation generator written by Jeremy Ashkenas under the MIT license. Docco generates html from source code with inlean documentation. Docco documentation is an html page in which both the source code and the documentation are presented. Take a look at jashkenas.github.com/docco. Installing Docco is very simple: npm install docco

This is a simple library that is easy to use if you are already using Node. If you want to try docco on your project, then install it from the root directory of your project, run: docco *.js

It is unusual that Docco places the source code next to the comments. JSDoc, in turn, will generate something similar to Prototype or jQuery documentation. I noticed that many simple Node libraries use Docco.

Ronn

Ronn , written by Ryan Tomayko and ronnjs can be used to generate documentation from a set of files. ronnjs limits us to only markdown files. The result can be presented in the form of HTML or man-documentation. The name Ronn comes from roff .

Github wikis

The GitHub project has a wiki, wiki markup sources are stored in Git. Wiki pages can be easily written in text format. Here's a blog post on GitHub that describes some of the features: Git-backed Wikis . This is a great tool for projects that need documentation outside the API, such as a FAQ, installation process, code samples.

GitHub also has GitHub Pages , which can be used to host static files on you.github.com. GitHub Pages can be used to store documentation generated by Docco or dox.

From translator

When translating, minor blocks of text were removed, representing deviations from the topic of the post.
Docco is not really as good as it seems at first glance, it requires a special kind of comments (single-line comments written on markdown)
he does not understand block comments. There is its analogue Pycco Rousseau-tourist written on Python, it generates exactly the same documentation and understands block comments, but again does not understand JSDoc blocks and distorts them (this is not meta tags).

Now I use a slightly modified default JSDoc template (JSDoc de facto documentation standard). After reading the article, I thought about switching to dox :

... I wanted something that could parse my javascript using markdown and jsdoc tags ...

Isn't that great ?!

What tool for code documentation do you use? What good tools do you know?