doxygen-users

RE: [Doxygen-users] XML documentation

[Catenacci, O. <Ono...@co...>]

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 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.
 
Just my opinion.
 
-- 
Onorio Catenacci
 
I don't speak for my company.
 

-----Original Message-----
From: Andre Loker [mailto:lo...@gm...]
Sent: Thursday, February 20, 2003 9:58 AM
To: Doxygen Mailing list
Subject: [Doxygen-users] XML documentation


Hi there!
 
I would like to create XML documentation from C++ sources. The generated
files have to be compatible with C# XML-documentation generated by the MS C#
compiler. Is it possible to tweak doxygen in such a way? I am quite new to
XML, does the solution lie in DTD or XML-schema?
 
Thanks in advance
 
- Andre Loker




The contents of this e-mail are intended for the named addressee only. It
contains information that may be confidential. Unless you are the named
addressee or an authorized designee, you may not copy or use it, or disclose
it to anyone else. If you received it in error please notify us immediately
and then destroy it. 

RE: [Doxygen-users] XML documentation

[Moshe K. <Kr...@Pa...>]

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: mk...@in...
-----------------------------------------------
APIs/SDKs * User manuals * White papers *
Training courseware * Marketing collateral


-----Original Message-----
From: Andre Loker [mailto:lo...@gm...]
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
Dox...@li...
https://lists.sourceforge.net/lists/listinfo/doxygen-users

Re: [Doxygen-users] XML documentation

[Andre L. <lo...@gm...>]

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