Fw: [Mono-list] Monodoc - doc generator
Jaroslaw Kowalski
jaak@zd.com.pl
Sun, 13 Jul 2003 15:13:16 +0200
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.
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
> ----------------------------------------
>