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

[Miguel de Icaza]

Hello,

> > 	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.

Well, currently we have a large directory checked into CVS for all the
Mono classes (mcs/docs/apidocs) without the assembly split.

I would like to make documentation "live" under a "doc" directory in
each assembly, so mcs would have mcs/class/corlib/doc/en for english for
instance and gtk# could have gtk-sharp/gtk/doc/en for english as well.

> >     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.

I am assuming that the 'reference' was the Microsoft assemblies here. 
That being said, I would like to just generate a skeleton of data
required, rather than having a stubbed-out document.  

This way we can use our incomplete assemblies as the "source" and just
keep upgrading the skeletons as our assemblies mature, without any
impact on the actual documents.

Say, for day 1 of the Mono project the skeleton would have only
contained one class: System.Object.   As we implemented more classes,
the skeleton would contain more classes to be documented.  

The skeleton would never contain any data, it would only list the things
that have to be documented, like for example:

	<class name="System.Object">
		<method>string ToString ()</method>
		<method>int    GetHashCode ()</method>
	</class>

	(or something like that)

All documentation would be placed in an external file (using the current
DTD is fine, I do not particularly care).  The GUI tool can then  use
this information to show what things are documented and which ones are
not. 

> This is what docstub does.  I think it should be pretty much feature complete since we use the
> NDoc reflection stuff.

Yes, docstub might be used here, but we have to remove the "stub" part
of it, ie, kill completely anything remotely looking like pre-filed
documentation.  All documentation should be kept outside.

The first time you launch the GUI editor, it can use the skeletons to
show what needs to be documented (everything  right now ;-) and any
documentation that is done, would go into its own file.

Now, lets say that the first day you document a single class,
System.Object.  Then the only file we check into CVS is
"System.Object.xml".  If someone contributes documentation
"System.String", we check "System.String.xml" as well. 

I hope I get my idea across.  If not, this is a good time to get
together, you tell me about your Parisian adventures, and we can get
some sushi or some coffee ;-)

Miguel.