I do not think that adding tags is the right thing to do, ultimately. I have to dig out some weave/tangle references with respect to SGML, but for the moment just for SGML: www.sgmltools.org What I think is that, within the /** javadoc */ pieces, SGML should be used instead of HTML. The most convenient thing would be restriction to one DTD - in this case, ORA's/Davenport group's DocBook DTD. There have been discussions about using JavaCC to generate SGML from Java source (parsing of class and method definitions is needed in any case). JavaCC (source n/a to my knowledge) is not a good choice, maybe. I suggested this once to javadoc-comments@sun. I was told that the SMI engineer responsible decided to use XML instead of SGML (doesn't make much difference to me, as XML is SGML with a different SGML declaration to my understanding). So, JDK 1.2 Javadoc (or 1.2.x or 1.x) is supposed ot use XML. See www.clark.com/xml/ for XP, a Java XML parser. I think the most crucical issue when replacing javadoc is to decide whether the source or the doc is primary. Javadoc still sees source as primary (readily compilable), while a weave/tangle approach requires an extraction to generate source. If one sticks to the javadoc approach, weaving the comments into the Java source becomes more involved. Java seems to be well suited for a web-like approach. Most coders abhorr this, though :-) Finally, the only Javadoc replacement I am aware of is doc++, which has long since been abandoned. It suffers from targetting HTML and LaTeX (mut-ex), instead of SGML. http://www.zib.de/Visual/software/doc++/. GPL'ed, so it might be worth a look (and maybe ripping of some stuff for a Java implementation). It parses C++ as well, so a lot of source could probably be omitted entirely. In any case: instead of a proliferation of @tags, I would suggest a simple extraction of /** */, preferably implicitely or eplicitely labelled and sorted by label, that create a valid SGML document in a DocBook or JavaDoc DTD. Generating implicitely labelled sections from classes, methods, and variables and adding them to the /** */ fragments (including predefined id's for cross references) stays a separate task then. See e.g. the doc++ /// comments for a counter-example. For a fistfull of cents, b. P.S.: wish I had the time to Do This Right...
