[Mono-list] Monodoc - doc generator

[Miguel de Icaza]

Hello,

> I've checked out monodoc from CVS and I've seen there is
> a tool named updater.exe in the "generator" directory.
> 
> update.exe takes an assembly as an input and then
> generates XML documentation stubs.
> 
> Does that means that I wouldn't be able to extract
> documentation comments from my C# source files at all?

Today our C# compiler does not extract documentation from the C# source
code, but it is something that is in our TODO list.

Monodoc is the framework to document the Mono class libraries, so we
have slightly different needs than the documentation typically embedded
in C# code.   There were various reasons why Mono as a project
decided a few months ago to use the ECMA XML file format as its master
file format as opposed to the C# markup, and they are:

	* Internationalization issues: documentation embedded in the
	  source code is only available in one language.  This possed
	  a problem: documentation for other languages had to be kept
	  on separate files, so we had to define a file format for this.

	  Basically, it would not be practical to have documentation in
	  30+ languages in the source code.   

	  It would also not be practical to track updates to the
	  documentation if it were to be embedded.

	* Inline documentation is best to document the workings of the
	  code and not necessarily the exposed API.  It might work for
	  smaller projects, but it becomes a liability to maintain the 
	  code to include all the documentation inline in our opinion.
	
	  Rotor's API documentation are a good proof of this: the
	  documentation is actually just "linked" from the main source
	  code, I imagine that they also encountered this problem.

	* Using the format that the ECMA group used to define the API
	  meant that we could bootstrap our documentation effort
	  quickly.  We have since extended this format to suit the needs
	  of Mono better (Some changes were done by Duncan, and more
	  recently Joshua Trauber has updated its format).

> Hai! That also means I've to manually move all the
> documentation comments from my C# source files into these
> generated stub files...

Another option is to contribute the code to extract the documentation in
C# source files, and contribute another monodoc provider;  That was one
of the design goals behind Monodoc (today we have three providers).

> Did the Mono team decide to not implement the -doc option
> for mcs.exe at all, or are there plans for future development?

It was not a priority, but as I said, at some point we will include it.

Miguel