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. 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.
In some distant past, some text editor developer thought it pretty to
generate...
/**
* @param foo {string} does bar
* @return {strong} gives blip
*
* bing bong
*/
..I don't agree at all that we need or want to see or write those
superfluous asterisks. Why would I bloat my code and documentation with
that? I'll never ever use emacs in my life. That boat has sailed.
To me, it's quite important that we input the documentation in precisely
the way we know it will render as a tiddler. This seems rather important so
as to make things right. Doing the mental yoga to anticipate what some
parser will do with it seems a rather poor design choice, imho. Let's stick
to *.tid* format! We don't need *jsdoc* for TiddlyWiki... and if others at
some point want to render a TiddlyWiki based documentation for their
(particular flavor of) *jsdoc* documented code, then there will (have to)
be someone willing to write that jsdoc parser that turns that into
tiddlers. Why would we waste time and energy on that? What we need rather
sooner than later is documentation that works for us, not this "standards
compliance" or that.
Keeping it simple and smart.
Also, I am against reinventing the wheel it just binds way too many
> developer resources. Implementing a comment parser with all features is a
> huge project. This is valuable time we (especially Jeremy) could use to
> make tw better. I use JSDOC to document the plugin api
> (http://bit.ly/tiddlymap_api)
> and I can only recommend it.
>
That's what I'm saying, let's not waste time on writing a jsdoc parser to
crank a lot of wheels so as to turn that into tiddlers! Let's use tiddler
format, because we sure know how to parse that and we know how those things
end up in TiddlyWiki! Simple, straight forward.
I'll put up a draft on GitHub on how I would envision this and perhaps we
can discuss the specifics there. I'd really appreciate if I never see those
asterisks in that doc... or any characters like @ that simply yield invalid
tiddler fields ...or are translated into some other string so as to be such.
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.
