On Apr 6, 10:21 am, Paul Downey <[email protected]> wrote:
> On 6 Apr 2009, at 10:14, Martin Budden wrote:
>
> > I favour forsaking the template altogether and writing a brief
> > description of the function, with a note describing anything unusual.
>
> +1 I think the params stuff is unnecessary duplication - It's more
> interesting to document what the function does, than force people into
> duplication of the function signature, which will no doubt soon go
> stale.
I generally agree that templatizing the parameter lists can be a lot
of effort for little gain and descriptive docs on the methods can be
far more useful. The inclination to document the parameters is often a
response to parameter profligacy, which is endemic in the existing
TiddlyWiki API, but perhaps will improve as part of this refactoring?
Methods should do one thing, well, with as few parameters as possible.
Their names should be as descriptive as possible. Complex behaviors
should be achieved by composition. Composition of public api methods
into other public api methods is handy.
However: my understanding of the point of this documentation project
is to make it possible to have a resource which provides a point of
entree into the TiddlyWiki development resource. In that context
templatizing _may_ make a great deal of sense.
But if you look at the ubiquity docs, which are using code illuminated
[1], the side by side appearance of docs and code tend to remove the
need for extensive chatter about parameters because you see it all,
right there.
Generally speaking _any_ documentation is going to be better than
none, but _no_ documentation is going to make up for an opaque API or
opaque functions and methods.
[1]
https://ubiquity.mozilla.com/hg/ubiquity-firefox/raw-file/347c22717e86/ubiquity/index.html#modules/utils.js
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
