Documentation-generator

[pheara]

• JSDoc vs YUIDoc vs Doxx vs Docco – Choosing a JavaScript documentation generator (2013/12)
• The best JavaScript documentation generator tools and reference builders (2013/11)

--> jsdoc uses the javadoc-syntax that most of us are already accustomed to and that intellij provides auto-completion for, is the easiest to skin among the reviewed tools and allows adding additional tutorial documents.

[pheara]

If you don't have auto-completion for the document structure, Smartcomments provides an online-tool, that generates YUI-style syntax that is relatively similiar to jsdoc (just drop the @method and @class annotations)

[pheara]

Apparently angular uses it's own flavour of jsdoc callged ngdoc.

[pheara]

Seems jsdoc has issues dealing with ES6. An alternative list of tools supporting ES6 can be found here: http://stackoverflow.com/questions/27334309/ecmascript-6-documentation-generators.

Of these ESDoc seems to be the most viable option. It finishes generating for the components-directory (but fails in our legacy-codebase halfway through with an error message that points to the right code-segment, which is a novelty compared to jsdoc's and dgeni's cryptic stacktraces). We'll need to update our documentation syntax as atm it only outputs empty documentation (and syntax-highlighted sources).

DGeni should support ES6 according to the following github-issue. However, we'll need an ndoc-configuration(?) from somewhere i assume (the gulp-task finishes without output atm). An example project can be found here: petebacondarwin/dgeni-example

[pheara]

postcss-style-guide would allow us to write the css-usage-example directly next to the css-classes (which should make it easier to keep them in-sync) and automatically generate a style-guide demoing all components.

[fkleedorfer]

maybe someday