Generate documentation files based on JSDoc comments

[Robbert]

I am considering using documentation for the purpose of generating documentation, because it uses the doctrine JSDoc parser which supports Google Closure Compiler Annotations.

• We should use our documentation stylesheet to improve readability of the generated documentation.
• Properly support grouping of properties, possibly by making groups explicit in JSDoc.
• Add documentation coverage.

[Robbert]

So I have looked at the the documentation package, by starting a generated documentation server using documentation serve src/freedom-0.org/robot/string/URI.js. First impression: theme is not very readable, and the UX isn't tailored to giving insight into large modules. There appears to be little distinction between public and private properties. It also appears no grouping of properties is supported: the grouping that is manually provided by defining properties on nearby lines of code, is undone by sorting all items alphabetically.

A quick glance at lodash revealed they use the @category Something annotation for this purpose.

[Robbert]

The default JSDoc notation for a return value is @returns, while Closure Compiler supports @return. Luckily, documentation has implemented the @return as an alias by default.

[Robbert]

I haven't yet discovered the documentation coverage statistics.

[Robbert]

Now I remember... devdocs.io has been open sourced a while back! This layout is so nice, their search works great, has offline support and it integrates with the documentation for the JavaScript APIs.

So maybe we can generate whatever they need for their documentation format and use this.

@Yolijn Good thing you learned CoffeeScript the other day, because that's what they used to develop this tool.

[Yolijn]

I looked at two npm modules for extracting documentation from JSDoc documentation with Closure Compiler annotations: documentation and documentjs. They are both able to output documentation with an interpretation of documentation for Closure Compiler. However, their approach is very naive:

• Each documentation line beginning with @ will be interpreted as Closure Compiler stuff and not be outputted directly. Only when the @ is followed by an implemented Compiler option ( param for example) will the output reflect the content of that line of documentation. Otherwise the whole line will be ignored.
• There is no interpretation of the code, no smart connections between function parameter names and @param names in the JSDoc

[Yolijn]

I propose we try the Lodash approach and use their Docdown npm module to generate markdown from JSDoc. Their approach: https://github.com/lodash/lodash/blob/master/lib/main/build-doc.js

We are then able to generate html (with Frameless even) from the generated markdown. The end result will probably still be as naive, but much easier to use, understand and mold to our desired output.