[Mono-docs-list] Re: Documentation, review.

[adam treat]

--- Miguel de Icaza <miguel@ximian.com> wrote:
> Hello guys,
> 
>    I have been looking at the current framework we have for
> documentation checked into CVS, and I think I would like to make a few
> changes to the way documentation works.  Here are my thoughts:
> 
> 	1. Assemblies should be each documented on its own, we should
> 	   not have a full merged set of documented.  
> 
> 	   This way, we can use the same tools to document Gtk# and
> 	   Qt#.  

I am not sure what you mean here.  Qt# will use the mono documentation tools as soon as they are
ready.  We will write a script to put our autogenerated comments into the external mono.xml files.
 I believe Rachel is planning to do the same, so I don't forsee any problems here.
 
> 	2. The merged "view" of all the documents should be taken care
> 	   at documentation install time, or by the GUI by importing
> 	   multiple documentation sources.
> 
>     I do not know where the templates we have right now came from: from
> our assemblies or from the Microsoft assemblies.   The templates have a
> number of problems: they are generated files, and hence, they are
> subject to be overwritten in the future.

The templates, aka stub xml files are generated by docstub.  It uses reflection to populate the
stub files.  The backend was taken from NDoc, but it requires no GUI driver.
 
>     What I would like for the "editing" tool, is a way to extract our
> "target" documentation skeleton from the MS assemblies (we can probably
> use CorCompare to do this), but this skeleton would not contain any
> documentation, it would only be the skeleton.  

This is what docstub does.  I think it should be pretty much feature complete since we use the
NDoc reflection stuff.
 
>     The editing tool could then show which nodes are missing, and which
> nodes have content.  We would only save actual content to our
> documentation files, never stubs or pre-generated output.
> 
> Comments?
> Miguel.

Ahh, I think I see what you mean.  You want to incorporate docstub more fully into the GUI... 
This way when someone decides to write the documentation for a specific class the stubbing will be
done at editing time.  I see the advantages of this in terms of file I/O and it shouldn't be more
difficult than what I was planning.  I will be home tomorrow.  I'll try to look at this then.

Adam


__________________________________________________
Do You Yahoo!?
Yahoo! Finance - Get real-time stock quotes
http://finance.yahoo.com