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 is highly similar to PHPDOC (http://phpdoc.org/docs/latest/index.html) to JAVADOC (http://en.wikipedia.org/wiki/Javadoc)... also it the standard at Google. If developers look at the tiddlywiki code they should feel familiar with the doc comments and not be scared or confused. > > 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. > It is a convention so your editor knows how to highlight the block-comments and people can see that each line belongs to a comment block dedicated to one topic. This has really nothing to do with emacs... 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! > Do you mean the dictionary format? How can I document nested objects with that or go multiline? > Keeping it simple and smart. > Do you want to write a parser that automatically does all the rendering and automatic linking? 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. > Why do you want to do this with tiddlywiki? This is just code documentation directed at developers. Joomla and Drupal are Content Management systems. Do they say: "let's develop and write our code docs in a joomla parsable format and publish it as a Joomla or Drupal Website?" So I am strongly in favour of using a standard here. -- 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 tiddlywikidev+unsubscr...@googlegroups.com. To post to this group, send email to tiddlywikidev@googlegroups.com. Visit this group at http://groups.google.com/group/tiddlywikidev. For more options, visit https://groups.google.com/d/optout.
