Results 1 to 5 of 5

Thread: Doxygen vs PCE2 for ClanLib 0.9

  1. #1
    ClanLib Developer
    Join Date
    May 2007
    Posts
    1,824

    Default Doxygen vs PCE2 for ClanLib 0.9

    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?
    Attached Files Attached Files

  2. #2
    ClanLib Developer
    Join Date
    May 2007
    Posts
    1,824

    Default

    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 **
    Attached Files Attached Files
    Last edited by rombust; 07-10-2007 at 08:54 AM.

  3. #3
    ClanLib Developer
    Join Date
    May 2007
    Posts
    1,824

    Default

    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)
    Last edited by rombust; 07-10-2007 at 12:13 PM.

  4. #4
    ClanLib Developer
    Join Date
    May 2007
    Posts
    1,824

    Default

    Ignore this entire thread

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

    sorry

  5. #5
    Master Sorcerer
    Join Date
    Sep 2006
    Location
    Denmark
    Posts
    554

    Default

    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.

Bookmarks

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •