Hi Tobias
That appears to quite constrain documentation abilities as there is no way
to address and manage individual functions other than render them somewhat
distinct from the surrounding code.
Do you mean that you want to browse the code by function/method rather than
by file/tiddler?
Do you mean that you want to browse the code by function/method rather
than by file/tiddler?
Basically yes, or rather both. I see the power in a full-blown TiddlyWiki
in its abilities to leverage individual tiddlers — in this case actualy API
functions and modules — rather than entire
All it takes is a rather simple build script (within TiddlyWIki), one that
isn't all too different from the one that creates TiddlyWiki itself... and
we're set.
With the approach that I'm suggesting we'd only need a build process for
generating static documentation snapshots. For interactive use,
For interactive use, you'd just install the JS parser and view the raw
tiddler modules to see the formatted documentation inline with the code.
That appears to quite constrain documentation abilities as there is no way
to address and manage individual functions other than render them
I think what you're missing is the jsdoc parser (and node integration)
is already written, and in fact has been long written, and stable.
On 2/5/2015 9:18 AM, Tobias Beer wrote:
I mean, we can sure implement jsdoc, but I believe it will
significantly slow down the process and make things more
Hi Tobi,
I find it difficult to agree. Perhaps that is owed to my not being a
hardcore developer but I would think that there factually is no such
hardcore documentation standard. There are project guidelines, styles and
implementations ...adopting this or that method, maybe jsdoc.
JSDOC
Hi Jim,
It DOES do all the function header and parameter parsing. It gives a
series of HTML pages that are all nicely cross-linked, decently styled and
perfect for the (already static) dev doc site.
That right there is the reason which makes it a no-go for me.
Frankly I am with Felix on
Hi,
I am thinking this is actually an area where we *definitely* should eat
our own dogfood.
When it comes to API docs, we should stick to standards like JSDOC. Code
needs to be documented in a most comprehensible and standard compliant way
to ensure other developers can pick it up and
It DOES do all the function header and parameter parsing. It gives a
series of HTML pages that are all nicely cross-linked, decently styled
and perfect for the (already static) dev doc site.
Frankly I am with Felix on this one. You think it won't be that much
effort to add it to TW, and maybe
I think what you're missing is the jsdoc parser (and node integration) is
already written, and in fact has been long written, and stable.
Ok, so what does it return? Is that usable for us? We still want to turn it
into tiddlers, at least I sure do. I don't want some pdf or HTML of which
I mean, we can sure implement jsdoc, but I believe it will significantly
slow down the process and make things more complicated for the TiddlyWiki
project... and only maybe easier for everyone else.
On the other hand, if you want to become familiar with TiddlyWiki's code,
maybe grab some
Hi Felix,
Do you mean the dictionary format?
How can I document nested objects with that or go multiline?
I mean a simple...
title:foo
bar:baz
text
...all neatly enclosed for doc'ing...
/**
title:foo
bar:baz
text
*/
If an editor needs superfluous asterisks to highlight comment
Hi Felix,
When it comes to API docs, we should stick to standards like JSDOC. Code
needs to be documented in a most comprehensible and standard compliant way
to ensure other developers can pick it up and understand it fast when
acutually reading the code.
I find it difficult to agree.
Hi Jim,
My point was simply that prefixing it with 1-n characters to create a doc
field namespace doesn't have to imply it has to be valid in HTML attributes
or wherever, because they can just be stripped out by the parser.
I think it's a lot better to use precisely what we're going to
Interesting...
On Thursday, January 29, 2015 at 9:50:14 AM UTC-6, Tobias Beer wrote:
*Imagine* this as a node package other package distributors can use to
generate the same type documentation by the click of a button, provided the
same commenting rules are parseable.
This makes me think:
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
On 2/1/2015 3:24 PM, Tobias Beer wrote:
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 see that as simply a marker that would be stripped by the parser. I
mean, we're not going to leave
I am thinking this is actually an area where we *definitely* should eat
our own dogfood.
In other words: find a way to parse and transform modules / code / comments
and output everything *into a TiddlyWiki* with proper fields / tags /
presentation / plugins.
*Imagine* this as a node package
18 matches
Mail list logo
