[Mono-list] Monodoc - doc generator
Jaroslaw Kowalski
jaroslaw.kowalski@atm.com.pl
Sun, 13 Jul 2003 13:35:20 +0200
This is a multi-part message in MIME format.
------=_NextPart_000_001C_01C34943.9AB38A80
Content-Type: text/plain;
charset="windows-1250"
Content-Transfer-Encoding: 7bit
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
>
------=_NextPart_000_001C_01C34943.9AB38A80
Content-Type: application/octet-stream;
name="monodoc2ndoc.cs"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: attachment;
filename="monodoc2ndoc.cs"
/*
Copyright (c) 2002,2003 Jaroslaw Kowalski <jaak@polbox.com>
All rights reserved.
Redistribution and use in source and binary forms, with or without=20
modification, are permitted provided that the following conditions=20
are met:
* Redistributions of source code must retain the above copyright notice, =
this list of conditions and the following disclaimer.=20
* Redistributions in binary form must reproduce the above copyright =
notice,
this list of conditions and the following disclaimer in the =
documentation
and/or other materials provided with the distribution.=20
* Neither the name of Jaroslaw Kowalski nor the names of its=20
contributors may be used to endorse or promote products derived from =
this
software without specific prior written permission.=20
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS =
IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, =
THE=20
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR =
PURPOSE=20
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE =
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR=20
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS =
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN=20
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)=20
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF=20
THE POSSIBILITY OF SUCH DAMAGE.
*/
using System;
using System.IO;
using System.Xml;
class Monodoc2NDoc
{
static bool wroteAssemblyInfo =3D false;
static int Main(string[] args)
{
if (args.Length < 2)
{
Console.WriteLine("Monodoc2NDoc - converts documentation from monodoc =
to ndoc format");
Console.WriteLine();
Console.WriteLine("Usage: monodoc2ndoc outputfile.xml dir1 dir2 .. =
dirN");=20
Console.WriteLine("");
Console.WriteLine("\toutputfile.xml is the name of file to create.");
Console.WriteLine("\tdir1..N are directory names to scan for =
documentation XML files");
return 1;
}
XmlTextWriter xw =3D new XmlTextWriter(args[0], =
System.Text.Encoding.UTF8);
xw.Formatting =3D Formatting.Indented;
for (int i =3D 1; i < args.Length; ++i)
{
ProcessDirectory(xw, new DirectoryInfo(args[i]));
}
xw.Close();
return 0;
}
private static void ProcessDirectory(XmlWriter xw, DirectoryInfo =
dirInfo)
{
Console.WriteLine("Processing directory {0}", dirInfo.FullName);
foreach (DirectoryInfo subdir in dirInfo.GetDirectories())
{
ProcessDirectory(xw, subdir);
}
foreach (FileInfo fi in dirInfo.GetFiles())
{
if (fi.Extension !=3D ".xml")
{
Console.WriteLine("Ignoring file: " + fi.FullName);
continue;
}
XmlDocument doc =3D new XmlDocument();
Console.WriteLine("Loading {0}", fi.FullName);
doc.Load(fi.FullName);
if (!wroteAssemblyInfo)
{
xw.WriteStartDocument();
xw.WriteStartElement("doc");
xw.WriteStartElement("assembly");
xw.WriteElementString("name", =
doc.SelectSingleNode("Type/AssemblyInfo/AssemblyName").InnerText);
xw.WriteEndElement();
xw.WriteStartElement("members");
wroteAssemblyInfo =3D true;
}
if (doc.DocumentElement.LocalName !=3D "Type")
{
Console.WriteLine("Ignoring file: " + fi.FullName);
continue;
}
string typeName =3D doc.SelectSingleNode("Type/@FullName").InnerText;
xw.WriteStartElement("member");
xw.WriteAttributeString("name", "T:" + typeName);
foreach (XmlElement el in doc.SelectNodes("Type/Docs/*"))
{
el.WriteTo(xw);
};
xw.WriteEndElement();
foreach (XmlElement member in doc.SelectNodes("Type/Members/Member"))
{
xw.WriteStartElement("member");
xw.WriteAttributeString("name", GetMemberNameString(member, =
typeName));
foreach (XmlElement el in member.SelectNodes("Docs/*"))
{
el.WriteTo(xw);
};
xw.WriteEndElement();
}
}
}
private static string GetParametersString(XmlElement member)
{
string par =3D "";
XmlNodeList nodes =3D member.SelectNodes("Parameters/Parameter");
if (nodes.Count !=3D 0)
{
par +=3D "(";
bool first =3D true;
foreach (XmlElement el in nodes)
{
if (!first)
par +=3D ",";
first =3D false;
par +=3D el.GetAttribute("Type");
}
par +=3D ")";
}
return par;
}
private static string GetMemberNameString(XmlElement member, string =
typeName)
{
switch (member.SelectSingleNode("MemberType").InnerText)
{
case "Event":
return "E:" + typeName + "." + member.GetAttribute("MemberName") + =
GetParametersString(member);
case "Method":
return "M:" + typeName + "." + member.GetAttribute("MemberName") + =
GetParametersString(member);
case "Field":
return "F:" + typeName + "." + member.GetAttribute("MemberName") + =
GetParametersString(member);
case "Property":
return "P:" + typeName + "." + member.GetAttribute("MemberName") + =
GetParametersString(member);
case "Constructor":
return "M:" + typeName + ".#ctor" + GetParametersString(member);
default:
throw new NotSupportedException("Unsupported MemberType: " + =
member.SelectSingleNode("MemberType").InnerText);
}
}
}
------=_NextPart_000_001C_01C34943.9AB38A80
Content-Type: application/octet-stream;
name="test.bat"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
filename="test.bat"
csc monodoc2ndoc.cs
monodoc2ndoc.exe corlib.xml M:\monodoc\class\corlib\en
------=_NextPart_000_001C_01C34943.9AB38A80--