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" <[EMAIL PROTECTED]> > To: "Jaroslaw Kowalski" <[EMAIL PROTECTED]> > Cc: "Mono" <[EMAIL PROTECTED]> > 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" <[EMAIL PROTECTED]> > > > To: "Giuseppe Greco" <[EMAIL PROTECTED]> > > > Cc: "Miguel de Icaza" <[EMAIL PROTECTED]>; "Mono" <[EMAIL PROTECTED]> > > > 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" <[EMAIL PROTECTED]> > > > > To: "Jaroslaw Kowalski" <[EMAIL PROTECTED]> > > > > Cc: "Miguel de Icaza" <[EMAIL PROTECTED]>; "Mono" > <[EMAIL PROTECTED]> > > > > 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" <[EMAIL PROTECTED]> > > > > > > To: "Giuseppe Greco" <[EMAIL PROTECTED]> > > > > > > Cc: "Mono" <[EMAIL PROTECTED]> > > > > > > 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 - [EMAIL PROTECTED] > > > > > > > http://lists.ximian.com/mailman/listinfo/mono-list > > > > > > > > > > > > > > > > > > > _______________________________________________ > > > > > > Mono-list maillist - [EMAIL PROTECTED] > > > > > > 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: [EMAIL PROTECTED] > > > > > web: www.agamura.com > > > > > ---------------------------------------- > > > > > > > > > > _______________________________________________ > > > > > Mono-list maillist - [EMAIL PROTECTED] > > > > > 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: [EMAIL PROTECTED] > > web: www.agamura.com > > ---------------------------------------- > > > > _______________________________________________ > Mono-list maillist - [EMAIL PROTECTED] > 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: [EMAIL PROTECTED] web: www.agamura.com ---------------------------------------- _______________________________________________ Mono-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-list
