[Mono-list] Monodoc - doc generator

[Jaroslaw Kowalski]

Hi!

Is there any tool (or is anybody working on it) to convert monodoc source
files to the xml format emitted by csc compiler?

This way, one could use it to produce nice output with ndoc.

Jarek

----- Original Message -----
From: "Miguel de Icaza" <miguel@ximian.com>
To: "Giuseppe Greco" <giuseppe.greco@agamura.com>
Cc: "Mono" <mono-list@ximian.com>
Sent: Saturday, July 12, 2003 11:20 PM
Subject: Re: [Mono-list] Monodoc - doc generator


> 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
> _______________________________________________
> Mono-list maillist  -  Mono-list@lists.ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-list
>