1303148 - Use a documentation generator

Status: RESOLVED FIXED

(L20n :: JS Library, defect)

Description

[Staś Małolepszy :stas]

Let's document our code with JSDoc comments and use one of the available documentation generators to generate html/md files from them.

Comment 1

[Staś Małolepszy :stas]

So I thought this would be easy… :)

I tried jsdoc3, esdoc, yuidoc and documentationjs.

jsdoc3 has the best HTML output but currently doesn't support some of the module syntax which we use.  We'd have to re-write our code a bit to avoid 'export' on the same line as the definition itself.

esdoc despite its name also doesn't support some of the common es2015 features like destructuring arguments in function signatures.

yuidocs spat a lot of errors at me and didn't extract anything useful.

Which leaves me with documentationjs.  It has a nice export to markdown but can't actually recurse into directories.  instead its default mode of operation is to start with an entry point and follow imports.  I don't think this would work well in our case where we have many entry points for many runtimes.  It would lead to a lot of repetition in the docs for each entry point.  It also has a --shallow option which disables this feature but it then need to be fed the list of files to extract docstrings from.

My current recommendation is to go with documentationjs and use wildcards in the makefile.  For instance src/intl/**/*.js would be used to generate docs/api/intl.md.  Once jsdoc3 or esdoc are fixed we can consider using them instead.  The priority right now, however, is to write the actual docstrings and using documentationjs is the easiest way to achieve that.

Zibi, do you agree?

Comment 2

[Staś Małolepszy :stas]

I found one more which might be a good choice for now: https://doxdox.org/

Comment 3

[Staś Małolepszy :stas]

Attachment: Pull request

With this approach each new file we'll want to put in the docs/ folder will require a new command in the makefile.

Comment 4

[Staś Małolepszy :stas]

https://github.com/l20n/l20n.js/commit/c7438984809050294b2cfd7030429453cb6d5d2a