Re: documentation system style?
Kris Kowal
On documentation style, I've been using a Javadoc-like syntax for
Chiron, and have tools for parsing and generating glossary-style
documentation. One of the other troubles with JavaScript
documentation is that you can't infer structure from the code; it must
be explicit in the doc. To this end, I use a system where /** docs */
are commentary that gets passed through to the underlying
documentation language. If there are more stars, it's a name.
/*** iter
returns an iteration of the values in a given iterable object.
- returns an `Iter` iteration instance
- accepts an `Iterable` instance
- `polymorphic`
*/
this.iter = operator('iter', 1, function (iterable) {
});
This is a little bit redundant, but short of writing a JavaScript
parser and inevitably failing to grok all of its syntactic forms (and
collect lots of false positives from various lambdas, I think that
reexplicating the name of the function is a small price.
Additional stars imply containment.
/** a module that provides a dictionary. */
/*** Dict
*/
this.Dict = type([Set], function () {
/**** iter
*/
this.iter = function () {
};
});
For the underlying comment language, I've been using ReStructured
Text. I've got about 150,000 words in comments (as calculated with
find, xargs, and wc -w between the difference in the built files and
the source). Not all of it's polished, per se, but it's a start. I
definitely want to add more stuff to the parser engine to glean
hyperlinks and organizational resources from the comments.
Kris.