Topic: C++ SDK documentation in wiki (and how you can help)

Last night I looked into the possibility of writing a bot to edit the C++ SDK pages in the wiki using the XML output of Doxygen. After figuring out how to work with the Mediawiki API I managed to more or less spam the Recent changes list at the end of the evening (since then I've been given the "bot" status thus hiding my changes in the normal listing).

How does it work? Well, the C++ SDK documentation has now two parts: the source-code-end and the wiki-end.

Source code
To document the API we need to put comments into all the public header files in the source code that Doxygen can parse.

Start by forking my Maratis repository at GitHub:

  https://github.com/dahnielson/Maratis

Switch to the development branch of your fork:

  https://github.com/dahnielson/Maratis/tree/development

Add comment blocks with triple slashes (///) to header files in the MSDK/MEore/Includes and MSDK/MEngine/Includes directories:

/// This is a description of class Foo.
/// Descriptions can span several lines if you wish.
class Foo
{
    /// This is a description of member function bar.
    void bar();

    /// This is a decription of member function baz.
    /// \param qux   this is description of the qux parameter
    /// \return          this is a description of the return value
    bool baz(int qux);
};

When you are done commit the change and send me a pull-request. BTW, it is possible to edit files of your forked repository directly in your web browser on GitHub.

Wiki
My newly created bot, aptly named Doxybot, parses the XML output that Doxygen generate from the documented source code and post the documentation to a special wiki page for each class. Doxybot uses the ids created by Doxybot as page name for each class, e.g. the class MBehavior become http://wiki.maratis3d.org/index.php?tit … sMBehavior. However that is not a page intended for humans to edit manually as the bot will overwrite any changes to the pages with names prefixed by "class". Instead the bot page is transcluded into the regular page http://wiki.maratis3d.org/index.php?title=MBehavior:

{{:classMBehavior}}

Everything around the transclusion on the regular page can be edited manually as normal for additional documentation.

Last edited by Dahnielson (2014-02-08 13:26:51)

  • 255
  • Member
  • Offline

Re: C++ SDK documentation in wiki (and how you can help)

Hi.
There are old information which was input manually e.g. bottom of MOEntity page.
I can easily put the general description of the class before the API list simply moving it before

{{:classMOEntity}}

but what about the old API information like this one:
http://wiki.maratis3d.org/index.php?tit … ties#Ghost
I guess it should be moved on the header files, although in this case you may loose the links inside the text.

  • 255
  • Member
  • Offline

Re: C++ SDK documentation in wiki (and how you can help)

Oh ok Doxygen automatically puts the link when it finds a class name.
But what if in the wiki I've something like this:

all the properties that will be used by the [[MPhysicsContext|physics engine]].

How can I simulate this in the header file?

Re: C++ SDK documentation in wiki (and how you can help)

255 wrote:

Hi.
There are old information which was input manually e.g. bottom of MOEntity page.
I can easily put the general description of the class before the API list simply moving it before

{{:classMOEntity}}

but what about the old API information like this one:
http://wiki.maratis3d.org/index.php?tit … ties#Ghost
I guess it should be moved on the header files, although in this case you may loose the links inside the text.

The general description of the class as documented in the header file will be on top of the page if it exist.

Move everything that's possible to the header file. However, the descriptiona in the headers should be brief. So any longer discussions that need to interlink to other wiki pages can be added to the wiki page itself at the bottom.

My idea is that the autogenerated API section will be on top of the page. Below it we can add further sections such as "Examples" or "Discussion" (or whatever we choose to call them) with more details.

Last edited by Dahnielson (2014-02-08 23:58:14)

Re: C++ SDK documentation in wiki (and how you can help)

255 wrote:

Oh ok Doxygen automatically puts the link when it finds a class name.
But what if in the wiki I've something like this:

all the properties that will be used by the [[MPhysicsContext|physics engine]].

How can I simulate this in the header file?

Simplest solutions is to just write:

all the properties that will be used by MPhysicsContext.

But I guess (haven't tested it yet) you could do:

all the properties that will be used by the \ref MPhysicsContext "physics engine".

From the Doxygen documentation:

Links to classes

All words in the documentation that correspond to a documented class and contain at least one non-lower case character will automatically be replaced by a link to the page containing the documentation of the class. If you want to prevent that a word that corresponds to a documented class is replaced by a link you should put a % in front of the word. To link to an all lower case symbol, use \ref.

\ref <name> ["(text)"]

Creates a reference to a named section, subsection, page or anchor. For HTML documentation the reference command will generate a link to the section. For a section or subsection the title of the section will be used as the text of the link. For an anchor the optional text between quotes will be used or <name> if no text is specified. For  documentation the reference command will generate a section number for sections or the text followed by a page number if <name> refers to an anchor.

  • 255
  • Member
  • Offline

Re: C++ SDK documentation in wiki (and how you can help)

I've sent a pull request. If it's ok, I can then do the other pages.

Last edited by 255 (2014-02-09 01:05:43)

Re: C++ SDK documentation in wiki (and how you can help)

255 wrote:

I've sent a pull request. If it's ok, I can then do the other pages.

Thanks! However, I left some comments on GitHub on how to improve it and closed it.

I've also edited the wiki pages that already had content on them into Example sections.

Last edited by Dahnielson (2014-02-09 11:17:01)