[Mono-docs-list] doctools: fork in the road?

[John Barnette]

At Saturday, 16 February 2002, Adam Treat <manyoso@yahoo.com> wrote:

>Hello All,
>
>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 
at NDoc 
>(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,
they 
>have been coding for quite sometime and far along.  With that said,
here are 
>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.


~ j.