Hi Jim, I think this is a very important topic ...it will get people up to speed with the TiddlyWiki core by magnitudes.
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! :). > /*doc tags: util documenting the below function */ Actually, "doc" could be a flag defined as a global setting for the function that extracts the documentation. Theoretically there could even be different flags being used for different purposes using the same mechanism. Here's my take on a "doc-tid" format... /*doc title: <should be automatic via rules, perhaps with an option to declare and thus overrule> tags: <depending on well defined tagging rules> namespace: $tw.utils <should be set on a file basis instead> function: getAttributeValueFromParseTreeNode <should be automatic!> arguments: node, name, defaultValue <should be automatic!> 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 summary: a short summary of what this function does 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 */ In addition, a *type* field could be specified so as to override the global default (rather than a "*format*" field). The *title* may be derived from a *namespace* set for an entire js file whereas all functions in that file are then appended to the namespace via dot notation. No sure we even need that function field. Ideally, it will be identified by the parser. Same for the *arguments* field! But maybe we simply use a set of prefixed field names, e.g., *docs*, *dox*, > or *twd*, or something Why? We know what fields we use in the docs, no prefix needed. We can't use @ as that is invalid in html attributes... an I don't see why we should. 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. > That is possibly true, but then I would have a global setting for the repo to define what format to use, which you could overwrite for a single tiddler by setting the *type* field accordingly. 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.
