Fw: [Mono-list] Monodoc - doc generator
Giuseppe Greco
giuseppe.greco@agamura.com
13 Jul 2003 15:04:09 +0200
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
----------------------------------------