I think the use of templates like this for function documentation
encourages the creation of tautological documentation. The current
example for TiddlyWiki.prototype.saveTiddler:
// Save tiddler to store
//#
//# N.B.: Does not trigger [[autoSaveChanges]].
//#
//# @param {String} title existing tiddler's title
//# @param {String} newTitle target tiddler's title
...
//# @param {Boolean} clearChangeCount reset tiddler's changecount
//# @param {Date} created date of initial creation
illustrates this pretty well. The documentation does not really tell
you anything you could not easily surmise by reading the function
signature. You are told that autoSaveChanges is not triggered, but
unless you know what this means, you don't know that the tiddler isn't
saved to file. The phrase "clearChangeCount reset tiddler's
changecount" is totally tautological and doesn not give a hint of what
changecount is used for.
I favour forsaking the template altogether and writing a brief
description of the function, with a note describing anything unusual.
So, for example,
"""
Save the tiddler to store, setting the dirty flag (so future calls to
saveChanges() will cause the store to be saved to file). Invoke the
notification handlers for the tiddler so that the story will be
updated.
Note that the modified and created parameters are date objects, not strings.
Martin
""
2009/4/4 Saq Imtiaz <[email protected]>:
>
>
>
> On Apr 4, 11:47 am, mahemoff <[email protected]> wrote:
>>
>> Does the use of wiki syntax mean that there's a plan for the doco
>> itself to fit into a tiddlywiki? I assume not...I assume it's just the
>> output of illuminated.
>
> The primary plan, as agreed upon on yesterday's developers' call, is
> just to document the code better in the JavaScript files themselves.
> Whilst we are doing so, we would like to decide upon a syntax for the
> comments that can be parsed by tools such as Code Illuminated, which
> would also leave the door open for a self-documenting TiddlyWiki.
>
> I think support for external links sounds like a sensible and fairly
> straight forward markup to support.
>
> Saq
> PS: Note that you can already Cook a TiddlyWiki with all the comments
> intact in the source of the document.
> >
>
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"TiddlyWikiDev" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/TiddlyWikiDev?hl=en
-~----------~----~----~----~------~----~------~--~---
