[Mono-list] Monodoc - doc generator

[Giuseppe Greco]

On Sat, 2003-07-12 at 23:20, Miguel de Icaza wrote:
> Hello,

Hi Miguel,
Hi Duncan,

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

That's great, but after reading this e-mail, I've fully understood why
you guys of the Mono team decided not to embed the documentation in
the source code.

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

            This is a good point; I hadn't taken in account 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.

            Right!
> 
> 	* 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.

I think I'll take my time and I'll convert my project to your standard.
Just few questions more:

You just run generator.exe and updater.exe manually, isn't it? You
probably run generator.exe once at the beginning and updater.exe
when new public or protected members are available, right?

Then, the makefile in the doc directory just invoke assembler.exe to
generate the documentation taking the previously generated XML file,
isn't it?

By the way, thank you very much for your good explanation!

Gius_.

> 
> Miguel
> _______________________________________________
> Mono-list maillist  -  Mono-list@lists.ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-list
-- 
----------------------------------------
Giuseppe Greco

::agamura::

phone:  +41 (0)91 604 67 65
mobile: +41 (0)76 390 60 32
email:  giuseppe.greco@agamura.com
web:    www.agamura.com
----------------------------------------