RE: XML documentation

BH

Andre, Hi!

I have had experience with Doxygen and NDoc.

I use Doxygen almost daily to churn out documentation for code developed in
C and C++. I respect Doxygen tremendously and it has helped my job-load
immeasurably.

When it came to producing documentation for a client developing in .NET and
C#, I came face to face with a brick wall.

Here are the problems:

1. Doxygen is simply not mature enough to deal with C# as it is in dealing
with C and C++. It is not oriented toward XML tags, which means you either
tweak a lot, or define your own XML tags for Doxygen that will match those
in .NET. 
2. The users of .NET and C# are accustomed to the standard Microsoft
look-and-feel, which you cannot accomplish with Doxygen, again without
developing your own CSS etc. (I have not attempted this. Perhaps it could
yield results.)

Now NDoc is a can of worms in its own right. I find it unwieldy and
inflexible. It often takes an hour for me to generate documentation because
of the way it is designed to work. If I want to see the results of some
change in documentation immediately, I know NDoc won't be there for me. I
guess I got spoiled with Doxygen.

I am crossposting this response to the nettwriters list on
http://groups.yahoo.com/. This is the reason: Following a suggestion on that
list, I began to examine the possibility of using a tool called Document X!
from www.innovasys.com. At least with a small .NET project, I got pleasing
results. The tool provides you loads of customization options and works
almost instantly. Most importantly, it produces MS-looking docs, replete
with class diagrams and so on. 

Their claim is that you can INTEGRATE THESE DOCS INTO THE VISUAL C# .NET
ENVIRONMENT. This sounds great, but I have not yet accomplished this.

To tell the truth, I have only tried out the evaluation version, so I am
still to be entirely persuaded. Nonetheless, it looks promising and my
collegues on the nettwriters list are convinced this is the way to go.

I am opening your issue up for discussion on nettwriters. At the same time I
hope our interchange will generate interest on Doxygen and challenge Dimitri
and co. to bring the C# solution up to scratch.

Moshe Kruger
AllWrite Information Design
Tel : 03-9607130
Mobile: 057-569-093
mailto: mkruger@xxxxxxxxxxxx
-----------------------------------------------
APIs/SDKs * User manuals * White papers *
Training courseware * Marketing collateral


-----Original Message-----
From: Andre Loker [mailto:loker@xxxxxx]
Sent: Saturday, February 22, 2003 3:18 PM
To: Doxygen Mailing list
Subject: Re: [Doxygen-users] XML documentation


Onorio Catenacci wrote:

> Define "compatible".  If you mean that the xml output from Doxygen must
use
> the same xml tags as the xml output from the MS C# compiler, then I'd say
> your simplest answer would be to use custom xml tags in your C# code that
> match those output by Doxygen.  Or you could feed Doxygen's xml output
> through an XSLT transformation and make it look like the xml output by the
> MS C# compiler.
I've started writing such an xslt-sheet, but I am not a specialist in XML
and/or XSLT, you see.

> I've looked at both the MS C# xml and Doxygen's output.  Doxygen's output
> is superior to the MS C# xml, in my opinion.  The MS C# xml seems to have
> been an afterthought.  I'd use Doxygen to document my C# code if I were
> you.

Of course doxygen is quite a powerfull tool and does its job very well, but
there are some things that NDoc (which uses C#-like xml) has that oxygen has
not. NDoc generates one page for each member, it groups compounds by
namespaces and of course supports features like properties and events. I
know doxygen is not intented to support MS specific extensions, nevertheless
those features were pretty cool. However, I prefer the documentation syntax
of doxygen - I don't like XML within my source code:

/// <summary>This is a brief description</summary>
class Foo
{

/// <summary>Brief description for a method</summary>
/// <param name="param1">A parameter</summary>
/// <returns>Returns 42 </returns>
int MyMethod(int param1);

};

looks much worse than

/// This is a brief description
class Foo
{
/// Brief description for a method</summary>
/// @param param1 A parameter
/// @return Returns 42
int MyMethod(int param1);
};


- Andre




-------------------------------------------------------
This SF.net email is sponsored by: SlickEdit Inc. Develop an edge.
The most comprehensive and flexible code editor you can use.
Code faster. C/C++, C#, Java, HTML, XML, many more. FREE 30-Day Trial.
www.slickedit.com/sourceforge
_______________________________________________
Doxygen-users mailing list
Doxygen-users@xxxxxxxxxxxxxxxxxxxxx
https://lists.sourceforge.net/lists/listinfo/doxygen-users


-------------------------------------------------------
This SF.net email is sponsored by: SlickEdit Inc. Develop an edge.
The most comprehensive and flexible code editor you can use.
Code faster. C/C++, C#, Java, HTML, XML, many more. FREE 30-Day Trial.
www.slickedit.com/sourceforge