[Mono-list] Monodoc - doc generator
Miguel de Icaza
12 Jul 2003 17:20:27 -0400
> 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.