code documentation
FND
jQuery-related refactoring of the TiddlyWiki core, Code Illuminated
might be of interest:
http://www.toolness.com/wp/?p=441
http://code.google.com/p/code-illuminated/
-- F.
FND
This turns out to be very simple to set up:
http://fnd.lewcid.org/tmp/Code_Illuminated/
After checking out the source, all I had to do was create a JavaScript
file[1] and add the "sample" link for it to index.html.
The only concern right now is the use of WikiCreole; we wouldn't wanna
use a different wiki syntax for the code documentation.
I assume making TiddlyWiki's formatters work with this would take quite
a lot of effort - so perhaps we could just tweak the existing Creole
parser[2] to support TiddlyWiki idiosyncrasies?
-- F.
[1] http://fnd.lewcid.org/tmp/Code_Illuminated/docs/foo.js
[2] http://code-illuminated.googlecode.com/svn/trunk/scripts/wikicreole.js
Alex Tsui
> The only concern right now is the use of WikiCreole; we wouldn't wanna
> use a different wiki syntax for the code documentation.
> I assume making TiddlyWiki's formatters work with this would take quite
> a lot of effort - so perhaps we could just tweak the existing Creole
> parser[2] to support TiddlyWiki idiosyncrasies?
some of the formatters in WikiCreole. Here's a patch against the js
file:
http://dl.getdropbox.com/u/508241/wikicreole.js.diff
In the patch, headings and bolding are changed to Tiddlywiki-style,
and I added some others like underline. I think the script looks for
the WikiCreole-style heading/bolding at the beginning of a comment to
trigger processing, so that's another file to change. Hope this helps.
--Alex T
FND
That's great - thanks!
I've updated the sample accordingly:
http://fnd.lewcid.org/tmp/Code_Illuminated/docs/foo.js
http://fnd.lewcid.org/tmp/Code_Illuminated/#docs/foo.js
> I think the script looks for the WikiCreole-style heading/bolding
Yep - was easy to fix though:
} else if (text.charAt(0) == "=" || text.charAt(0) == "*") {
vs.
} else if (text.charAt(0) == "!" || text.charAt(0) == "*") {
(that's on l. 104 of docs/docs.js)
-- F.
Saq Imtiaz
it. I recall having conversations with Jeremy and others at Osmosoft
over a year ago about formalizing how we document our code and jsdoc
was discussed. At the time it was felt that we might be better off
rolling our own solution but here we are about 18 months later and we
just haven't had the time. In hindsight it seems very obvious that we
should make use of available tools in such situations so as to focus
our attention where it is really needed.
One thing to keep in mind with code illuminated is that the
documentation should remain easy to read in the code itself (i.e.
without external tools) - so we should only use/allow a very limited
subset of wiki syntax in order not to obscure the documentation with
excessive markup.
Saq
FND
> order not to obscure the documentation with excessive markup
I absolutely agree.
Question is, what should that minimal subset be, and which patterns do
we need.
The most important part, of course, are function signatures.
Since JSDoc* is the traditional choice here, let's see what that would
look like:
/**
* <summary>
*
* @param {<type>} <name> <description>
* @returns {<type>} <description>
*
* <details>
*/
function foo( ... ) { ... }
While this often isn't very readable (esp. WRT distinguishing argument
names and descriptions), the basic structure - flag plus slots for type,
name and description - is useful.
So here's what I imagine we might end up with:
//# !foo
// <summary>
//#
//# * param <name> (<type>): <description>
//# * returns (<type>): <description>
//#
//# <details>
function foo( ... ) { ... }
(Note: Using individual "//" and "//#" markers instead of "/* ... */"
because that's what Cook understands.)
As for supported markup, I think headings, lists, italics, monospace and
links would probably suffice for starters.
(Note that internal links don't seem to be supported yet.)
We should agree on these basics ASAP so we can start on the actual
documentation.
-- F.
Saq Imtiaz
On Mar 30, 2:27 pm, FND <F...@gmx.net> wrote:
>
> While this often isn't very readable (esp. WRT distinguishing argument
> names and descriptions), the basic structure - flag plus slots for type,
> name and description - is useful.
>
> So here's what I imagine we might end up with:
> //# !foo
> // <summary>
> //#
> //# * param <name> (<type>): <description>
> //# * returns (<type>): <description>
> //#
> //# <details>
> function foo( ... ) { ... }
> (Note: Using individual "//" and "//#" markers instead of "/* ... */"
> because that's what Cook understands.)
prefer the usage of : after argument names
>
> As for supported markup, I think headings, lists, italics, monospace and
> links would probably suffice for starters.
that is a good start and rather than spend more time guessing what we
might need, we should start using it and adapt as we go along.
> We should agree on these basics ASAP so we can start on the actual
> documentation.
as a good chance to address that need as we are going to get.
What can I do to help?
Saq
>
> -- F.
>
> *http://jsdoc.sourceforge.net/
mahemoff
> As for supported markup, I think headings, lists, italics, monospace and
> links would probably suffice for starters.
documentation, for example).
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. It's a nice idea though, to think of a special
developer's TiddlyWiki build that ships with tiddlers containing cod/
API explanations.
Saq Imtiaz
On Apr 4, 11:47 am, mahemoff <mahem...@gmail.com> 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.
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.
Martin Budden
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 <lew...@gmail.com>:
Paul Downey
> 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.
Paul (psd)
--
http://blog.whatfettle.com
chris...@gmail.com
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
FND
> encourages the creation of tautological documentation.
> I favour forsaking the template altogether and writing a brief
> description of the function, with a note describing anything unusual.
I fully agree.
This is something I've often struggled with - a good function signature
usually makes parameter documentation redundant - and I think your
conclusion is very reasonable.
(FWIW, I think that the reference to autoSaveChanges is actually
important in this example.)
So we should now be able to Just Do It.
Perhaps I'll look into extending the parser with basic support for
internal links, as that might be handy (e.g. in the case of saveTiddler
referencing autoSaveChanges).
-- F.