On 2/1/2015 6:36 PM, Tobias Beer wrote:
What trailing colons do you mean?
The ones separating the field name from the field content, e.g.:
title: Foo
^ - that one.
My point was simply that prefixing it with 1-n characters to create a
doc field namespace doesn't have to imply it has to be valid in HTML
attributes or wherever, because they can just be stripped out by the parser.
To me, with a doc-tid, we're looking at a plain tiddler definition, no
special parsing,
Well, except for the fact we're in a Javascript comment. :) And that
means we're going to have to deal with this:
/*doc
_summary: blah
*/
...as well as this:
/*doc
* _summary: blah
*/
...as well as this:
/*doc
** _summary: blah
*/
...unless we prohibit all but the first format.
Honestly, my original thoughts on this was to stay somewhat close to
YUI/Javadoc "standards" (conventions), because those are known to a
wider audience and I was hoping to get some tool reuse. That isn't
saying I think you're wrong - I just wonder how much wheel reinvention
we'll have to do, especially if we begin parsing the function/property
name and parameters directly instead of having them explicitly defined
in the doc fields? Which, again, I don't think is wrong, but increases
the complexity of the solution. "The perfect is the enemy of the good
<https://en.wikipedia.org/wiki/Perfect_is_the_enemy_of_good>" and all that.
True, with my first proposal above, if we had an argument called
*title* or *type* we had a bit of a problem: We sure can't set a
*title* or *type* field without breaking TiddlyWiki's representation.
The simplest workaround would indeed be to prefix all fields. How
about underscore, e.g. *_type*?
So, to putting it all together once more...
|
/*doc
_summary: a short summary of what this function does
_namespace: $tw.utils <should be set on a file basis instead of per
doc-tid>
_function: <should be automatically parsed from the function head!>
_arguments: node, name, defaultValue <should be automatically parsed
from the function head!>
_node: (type of node) description of node
_name: (type of name) description of name
_value: (type of defaultValue) description of defaultValue
_return: (type of return value) description of return value
title: <should be automatic via rules, perhaps with an option to
declare and thus overrule>
tags: <depending on well defined tagging rules>
type: text/markdown
additional information, if there needs to be any, e.g.
cross-references with other functions
## Example
A common example of how to use this function, if useful.
*/
|
I could live with that.
Question: How do you see module/"class"-level documentation working?
Right now we have this:
/*\
title: $:/boot/boot.js
type: application/javascript
The main boot kernel for TiddlyWiki. This single file creates a
barebones TW environment that is just sufficient to bootstrap the
modules containing the main logic of the application.
On the server this file is executed directly to boot TiddlyWiki. In the
browser, this file is packed into a single HTML file.
\*/
Is that enough? Just extract that text, stick it under a "boot.js"
header/tiddler and be done?
Another thought. If we're going to parse out the functions/properties,
it would be an interesting exercise (I think) to have an automatically
generated "references/referenced by" set of links, too. But that
increases the complexity even more! :)
--
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.
