[Mono-docs-list] doctools: fork in the road?
Sun, 17 Feb 2002 10:30:05 -0600
At Saturday, 16 February 2002, Adam Treat <firstname.lastname@example.org> wrote:
>Here is the deal. I have been working diligently on all of the
tools and am
>ready to commit something to cvs. I've also recently taken a look
>(GPL'd ndoc.sourceforge.net) as John Barnette has suggested and
this has led
>to an impending decision of sorts. The NDoc stuff is very impressive,
>have been coding for quite sometime and far along. With that said,
>the choices I see for the road ahead:
Adam, et. al,
Just wanted to make a couple of points in the course of this decision:
I don't think we really lose a lot of information by keeping our
external XML documentation in the same schema as the output of csc
/doc. We would want to add a 'lang' attribute to the root element
(so we can store different language versions in different files),
but I don't think it's really missing anything. We can also generate
stubs for these documents without adding /doc functionality to mcs
(something, I should stress, that we really should do sooner or later).
See, we've really got two issues to address here:
1. Documentation support for Mono class library development.
2. Documentation support for people using Mono to build other projects.
(2) is pretty simple: as stated above, mcs should support --doc,
producing identical output to csc /doc.
(1), which is what we care about now, is a bit more complicated,
as we've added a few extra requirements already:
* API documentation will not be inline, and will rather be stored
in external files.
* Support must exist for multiple languages.
My suggested approach:
1. A tool (docstub) that reflects over a compiled assembly, and, given
a target language, creates an XML documentation stub file for the
assembly, with an additional 'lang' attribute. This file's format
is nearly identical to the output of csc /doc.
Let me clarify, as that's a bit inaccurate: I believe that there
should be an XML documentation file for EACH TYPE in an assembly,
not one file for the entire assembly. Having one file would make
edits and merging an absolute nightmare.
2. A tool (pretty simple) that creates a single XML (compatible with
csc /doc) file from the collection of XML files for all the types
in an assembly, given a language to use.
3. A tool to combine this document with more advanced assembly metadata
to produce presentation-ready XML, and create HTML, PDF, and other
forms of end-user-readable documentation. NDOC fits here, and,
assuming that (1) and (2) are implemented, NDOC should be able
to read the combined XML file from step (2) with no problems.
4. A GUI tool for editing type documentation, aiding translation
efforts, and providing coverage checks, et cetera.
One other note: I don't think that NDOC's output requires the Microsoft
help viewer. I'm pretty certain that the HTML produced can be simply
accessed through a browser.