Doxygen vs PCE2 for ClanLib 0.9

[rombust]

For those who do not know, Doxygen and pce2 are source code documentation systems that extract comments from the source code to create html documentation.

Doxygen is found at: http://www.stack.nl/~dimitri/doxygen/ and is available on Linux/Windows.
PCE2 is found at ClanLib-0.9/Documentation/Reference/pce2 and requires perl to run

It is strange writing this message, many years ago there was a similar discussion, and pce2 was chosen. Back then i preferred pce2, however since then, Doxygen has advanced a lot.

I use doxygen at work, and have grown to admire it for it's flexibility. See http://kdevelop.org/HEAD/doc/api/html/ for an example.

There are these options:
1.Keep pce2, and do not support doxygen
2.Keep pce2 and support doxygen
3.Use doxygen and drop pce2

Option 1)
No additional work required

Option 2)
I have created a program to convert the pce2 style source code comments to doxygen style comments as follows:
"//:" --> "//! \brief"
"//-" --> "//!"
"//param " --> "//! \param"

See attached file (srcdox.cpp in the zip) for my converter program. The entry point is: srcdox_main()

Option 3)
Use my converter program to convert the comment style, and write the output back to SVN. Drop pce2.

It should be possible to make the ClanLib documentation using Doxygen look like the pce2 html, with further tweaks as follows:
Create source code groups (For Display, Core, GUI etc) using "//! /defgroup"
Create a html header and footer

I did have an example, however, i cannot upload it (rtsoft complained "out of memory", even with a 3 mb zip (with a few thousand files)

If you want an example, there is a lot out there on the internet... for example http://svn.wikimedia.org/doc/

Any Comments?

[rombust]

I had a quick look at using doxygen groups.

In addition to my last message:
Change:
//! clan{xxx}="{yyy}"
To:
//! \addtogroup CLANLIB_GROUP_{xxx} {xxx}
//! \{
//! \addtogroup CLANLIB_SECTION_{yyy} {yyy}
//! \{
(With a matching "//! \} \n //! \}" at the end of the file)

Attached is a HTML example. Note, the doxygen buttons at the top will not display correct in the example, as the html requires tabs.css

As a test the example uses an additional groups: enums and classes... but this would require manually editing the source code to implement

** Rename modules.txt to modules.html **

[rombust]

An updated modules.html, i missed most of the API :)

(rename modules.txt to modules.html)

And an updated srcdox.cpp

(rename srcdox.txt to srcdox.cpp)

And a screengrab (screenshot.png)

[rombust]

Ignore this entire thread :D

cl2doxy.pl does what my converter program does (except much more efficiently). That is called from clanlib.doxygen that is already in clanLib

sorry :)

[Magnus Norddahl]

Yep, the plan in 0.9 is to use doxygen with a custom written XML to HTML converter (ClanLib-0.9/Utilities/Reference in svn) which converts from doxygen's XML output to the HTML layout that is currently in use on clanlib.org for the 0.9 reference docs.