Hi Jim, > I see that as simply a marker that would be stripped by the parser. > I mean, we're not going to leave the trailing colons in the names either, > true? :) >
What trailing colons do you mean? To me, it is a way for a parser to quickly rip through a file looking for > just the strings it cares about, and something like /@([a-z]+):/i (I > haven't tested that regex :) ), > To me, with a doc-tid, we're looking at a plain tiddler definition, no special parsing, except for the function head that follows it, to get both the title and the arguments and that's it. We already get those arguments in the right order; all we need is to remove those commas. No need for any regexp voodoo in the actual doc-tid. As for the function title, we may need to handle / replace some namespace prefix for a file, e.g. *module.exports* is hardly what we want, so perhaps a file could start with... //doc _namespace=$tw.utils ...and then keep adding the bit behind the last dot in that function title to construct the function title. If ever necessary, the _namespace field could be manually set for each individual doc-tid. I can see where modules would need some "documentation" fields as well as > normal "TiddlyWiki" fields, and was trying to namespace the documentation > fields basically, so that we could have a something like: > 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. */ Stripping the above down to the minimum, assuming the rest was parsed from the function head or otherwise defined via defaults, or not necessary... /*doc _summary: this function does yada _node: (node) the [[node]] bla _name: (string) blip name blup _value: (number) the bleep value _return: (boolean) true: foo / false: bar tags: utils */ Best wishes, Tobias. -- 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.
