Interesting... On Thursday, January 29, 2015 at 9:50:14 AM UTC-6, Tobias Beer wrote: > > *Imagine* this as a node package other package distributors can use to > generate the same type documentation by the click of a button, provided the > same commenting rules are parseable. > > This makes me think: Should code-comments actually be in the format of > *.tid* files? This would make parsing enormously straight forward. > > All we needed was some conventions on how to populate which (standard) > fields, tags, text-templates with content. Perhaps some helper macros to > cross-reference. >
If we used some sort of "code fencing" in the comments, we could easily discriminate between comments that had documentation in them and ones that didn't (i.e., we don't want to pick up every block comment, because some may be, well, comments! :). Something like YAML block markers, but not as ugly. :) YUI simply uses an extra asterisk at the start of the block: /** <docs go here> */ ...but that seems a bit ambiguous. I like Jeremy's "arms" block markers on modules: /*\ <docs go here> \*/ I agree, if we can come up with some field names we all agree on, they could then simply be tiddler-formatted. I worry a bit about collisions with field meanings already in use (around modules, for example). But maybe we simply use a set of prefixed field names, e.g., *docs*, *dox*, or *twd*, or something - or even take a page from YUI <https://yui.github.io/yuidoc/> and similar Javadoc-based formats and simply use *@ *as a field name prefix. For example, given a Javascript function *foo*: /*\ @method: foo @params: bar, baz @return: string @format: text/x-markdown This function gonculates the output using the [xyzzy](http://somewhere.com/xyzzy) algorithm on the `bar` and `baz` parameters. \*/ function foo(bar, baz) { ... If we don't try and get fancy to start by not auto-detecting function names and parameters and having them documented explicitly as fields, I agree it would seem like it could be a fairly straightforward approach. I think we need to make sure we support Markdown as well as tiddlytext to start because if we want others (outside the TW community) to use it to produce documentation TWs per your suggestion, I think MD would need to be supported simply because it is more ubiquitous for that purpose, thanks to Github, etc. An interesting question to me would be how to document multiple parameters, each of which could get quite complex? YUI uses repeating fields: /** * My method description. Like other pieces of your comment blocks, * this can span multiple lines. * * @method methodName * @param {String} foo Argument 1 * @param {Object} config A config object * @param {String} config.name The name on the config object * @param {Function} config.callback A callback function on the config object * @param {Boolean} [extra=false] Do extra, optional work * @return {Boolean} Returns true on success */ I don't think that would work with TW fields, would it? And while a field that is a list (see my *@params *above) would work for parameters, it would be unwieldy for complex parameter documentation showing options, TW/MD markup, etc. Maybe we just come up with a convention that everything from the start of a *@params* field until the next field or blank line are parameters, and have some conventions around those: /*\ @method: foo @params: * bar (string) - The starting string for `xyzzy`. An error is thrown if it is missing. * baz (string, optional) - The ending string for `xyzzy`. If missing, `plugh` is assumed. @return: string @format: text/x-markdown This function gonculates the output using the [xyzzy](http://somewhere.com/xyzzy) algorithm on the `bar` and `baz` parameters. \*/ function foo(bar, baz) { ... -- You received this message because you are subscribed to the Google Groups "TiddlyWikiDev" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/tiddlywikidev. For more options, visit https://groups.google.com/d/optout.
