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 find in TiddlyWiki, no special handling or logic... except within the TiddlyWiki output template itself. that means we're going to have to deal with this: > > /*doc > _summary: blah > */ > > ...as well as this: > > /*doc > * _summary: blah > */ > > ...as well as this: > > /*doc > ** _summary: blah > */ > The way I see it, we don't have to deal but with the first. Let's start by defining our pattern and that's it. No catering for all possible styles to begin with. If later on someone desperately wanted that, we can perhaps try and cater for it, and perhaps get a small paycheck for it, but not when we start out. To me, using a simple tid format is of utmost importance because that is precisely what guarantees compatibility with TiddlyWiki. > ...unless we prohibit all but the first format. > So, yes, that is what I would recommend. Let's not try to make ammends for the whole world but start with something that works perfectly well with our not so small project. We have enough work ahead to produce our own documentation, rather than writing parsers for someone else's. Let's not imagine all possible things anybody could want but strip it down to a basic set to start out with, one that makes sense for doing this kind of thing with TiddlyWiki. Adapting an existing project to TiddlyWiki style documentation will need manual intervention anyway, so... I don't see why we would start out with requirements imagining all possible documentation styles people may have come up with, e.g. YUI. Perhaps later there could be custom parser modules to convert such custom comment formats to tid format, but that's surely not how we would start, at all. Let's *NOT* compete with YUI trying to get our thing working for their crew. If that's a challenge you want to live up to, do it later, after we're set ourselves. Honestly, my original thoughts on this was to stay somewhat close to > YUI/Javadoc "standards" (conventions), because those are known to a wider > audience and I was hoping to get some tool reuse. > That is precisely where I believe you're making a big mistake. There is no point for us in trying to adapt to any more-or-less-standard. We can perfectly define one ourselves, based on tiddlers, imho. Why would you pick YUI? You could pick any arbitrary project standard. Let's not do that. I just wonder how much wheel reinvention we'll have to do, especially if we > begin parsing the function/property name and parameters directly instead of > having them explicitly defined in the doc fields? > If you ask me, trying to adapt to a standard that doesn't suit our pattern actually is reinventing a wheel, their wheel, and trying to make it fit to our vehilce whereas we already have wheels lying around that do quite nicely for the thing we want and need to get going, namely the tid file format. Those fit perfectly to the vehicle called TiddlyWiki. > Which, again, I don't think is wrong, but increases the complexity of the > solution. "The perfect is the enemy of the good > <https://en.wikipedia.org/wiki/Perfect_is_the_enemy_of_good>" and all > that. > So, to perhaps draw that bottom line, catering a number of possible commenting styles, is what I would call increasing complexity. Let's not do that. Question: How do you see module/"class"-level documentation working? Right > now we have this: > /*\ > title: $:/boot/boot.js > type: application/javascript > The main boot kernel for TiddlyWiki. This single file creates a barebones > TW environment that is just sufficient to bootstrap the modules containing > the main logic of the application. > On the server this file is executed directly to boot TiddlyWiki. In the > browser, this file is packed into a single HTML file. > \*/ That would need some adjusting. At least there would have to be a newline after type. Never took a look at the process, but I can imagine that this stuff is parsed to actually build the core component tiddlers. So, here we're not only in "documentation-land" but rather in build-territory. I would sure not want to see any *_namespace:foo.bar* or *_summary:this file does bla* see in the distro, but rather only in the documentation wiki. We could possibly ignore any of those that start with underscore in the build-process, including the text. I think it's perhaps not a good idea to intermingle the two. My tentative recommendation: have one block for the build instructions and another for the file documentation. /*doc-module _namespace: bla.blup _summary: this file defines the foo class details, details details... */ Is that enough? Just extract that text, stick it under a "boot.js" > header/tiddler and be done? > So, nope, I think there would either have to be some parsing rules for that block or some form of separator if one wanted both in one. If you think of other projects, they will not have TiddlyWiki built instructions but their own. So, documentation and built / test comments should sure be separated. As a sidenote, I also don't think that any of that documentation content, build comments, jshint comments, etc.. should ever end up in the distro. But that, too, is a thing for another day... hopefully not too far down the road. > Another thought. If we're going to parse out the functions/properties, it > would be an interesting exercise (I think) to have an automatically > generated "references/referenced by" set of links, too. But that increases > the complexity even more! :) Let's take it one step at a time. ;-) Surely, if we set the *_namespace* field correctly and know some *function* name for which we create a doc-tid we could easily have a list in a conditional wiew-template within TiddlyWiki that queries the tiddler store exactly for that and lists occurences at the documentation tiddler in a slider. This could also list results where *_namespace:foo* matches in a file head and then references to that function via *this.someFunction* or perhaps *self.someFunction*. there could also be fuzzy matches just listing occurences of the plain function name... all within TiddlyWiki itself, nothing that the "build-process" for the documentation would do. The big chunk of the logic will be within the target / template TiddlyWiki, not some node-comment-parser(!) That parser should be as simple and light-weight as possible, imho. 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.
