[Mono-list] Monodoc - doc generator

[Giuseppe Greco]

On Sun, 2003-07-13 at 10:39, Jaroslaw Kowalski wrote:
> 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.

I think this would be really nice...

We have developed our system with Mono on Linux, but to produce
the first version of the SDK documentation, we had to switch to
Windows...

At that point, before we proceed with our project, we have to
fix the documentation issue, so that in the future we will not
have to setup a Windows machine any more just to generate the
documentation.

The nice thing with ndoc is the possibility to generate LaTeX
source, from which one can generate either PDF or PS output.

We would like to automatically generate our documentation in
the following formats:

. ECMA
. HTML
. PDF

By the way, since our development platform is Linux only, and we
decided to use the Mono framework only, for the moment it would
be enough to get the documentation generated with what is available
right now.

Would it possible to get a step-by-step description of how to
setup a documentation project based on monodoc?

Gius_.

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