Fw: [Mono-list] Monodoc - doc generator

Giuseppe Greco giuseppe.greco@agamura.com
13 Jul 2003 15:23:43 +0200


On Sun, 2003-07-13 at 15:13, Jaroslaw Kowalski wrote:
> As far as I remember namespace summaries are stored as part of ndoc
> configuration files (or inline in NAnt build files) rather than instead of
> the documentation XML files.
> 
> In *.ndoc files you have for each namespace:
> 
>     <namespaces>
>         <namespace name="bleble">bleble</namespace>
>         <namespace name="bleble">bleble</namespace>
>         <namespace name="bleble">bleble</namespace>
>         <namespace name="bleble">bleble</namespace>
>         ...
>     </namespaces>
> 
> csc compiler doesn't let you attach comments to namespaces and there's no
> specific format for storing them.

Ah yes, of course, you are right! Sorry, but this is the result
when one sits in front of a PC too much...

Gius_.

> 
> Jarek
> 
> ----- Original Message -----
> From: "Giuseppe Greco" <giuseppe.greco@agamura.com>
> To: "Jaroslaw Kowalski" <jaak@zd.com.pl>
> Cc: "Mono" <mono-list@ximian.com>
> Sent: Sunday, July 13, 2003 3:04 PM
> Subject: Re: Fw: [Mono-list] Monodoc - doc generator
> 
> 
> > On Sun, 2003-07-13 at 14:11, Jaroslaw Kowalski wrote:
> > > Hi Giuseppe,
> > >
> > > can you check if it works for you on Linux?
> >
> > Jarek, Wow!
> >
> > I've tested you documentation generator with Mono on
> > Linux and it works fine. Well done!
> >
> > Just a hint: would it be possible to also process XML
> > files describing namespaces? For instance, I've
> > structured my documentation project like this (I took
> > the gtk-sharp project as a template):
> >
> > doc
> >  +-en
> >    +-Gekkota.Core.xml
> >    +-Gekkota.Core
> >          +-Datagram.xml
> >          +-Listener.xml
> >          +-Omnicaster.xml
> >          +-...
> >
> > Right now, monodoc2ndoc does process the file in the
> > Gekkota.Core directory, but doesn't process the file
> > Gekkota.Core.xml. Gekkota.Core.xml describes the
> > namespace.
> >
> > By the way, I think we have to wait till tomorrow to
> > get feedback from the Mono community...
> >
> > Again, well done and thank you very much!
> >
> > Gius_.
> >
> > >
> > > Jarek
> > > ----- Original Message -----
> > > From: "Jaroslaw Kowalski" <jaroslaw.kowalski@atm.com.pl>
> > > To: "Giuseppe Greco" <giuseppe.greco@agamura.com>
> > > Cc: "Miguel de Icaza" <miguel@ximian.com>; "Mono" <mono-list@ximian.com>
> > > Sent: Sunday, July 13, 2003 1:35 PM
> > > Subject: Re: [Mono-list] Monodoc - doc generator
> > >
> > >
> > > > Hi all!
> > > >
> > > > I really needed that tool so I sat down and wrote it. It's attached to
> my
> > > > e-mail and everyone is free to use it (BSD license).
> > > >
> > > > It's ultra quick-and-dirty, so please excuse its design.
> > > > Usage is very simple, and batch file used for testing is attached.
> > > >
> > > > Please note, that this tool was only tested on Windows/.NET 1.1 but
> should
> > > > work on Mono/Linux without any changes.
> > > >
> > > > Can someone add this to monodoc CVS directory?
> > > >
> > > > Jarek
> > > >
> > > > ----- Original Message -----
> > > > From: "Giuseppe Greco" <giuseppe.greco@agamura.com>
> > > > To: "Jaroslaw Kowalski" <jaak@zd.com.pl>
> > > > Cc: "Miguel de Icaza" <miguel@ximian.com>; "Mono"
> <mono-list@ximian.com>
> > > > Sent: Sunday, July 13, 2003 12:25 PM
> > > > Subject: Re: [Mono-list] Monodoc - doc generator
> > > >
> > > >
> > > > > 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
> > > > > ----------------------------------------
> > > > >
> > > > > _______________________________________________
> > > > > 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
> > ----------------------------------------
> >
> 
> _______________________________________________
> 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
----------------------------------------