Docu style

[mrwonko]

I'm about to start documenting the code. While reading functions I'll improve their documentation to help me get a better understanding, which will help with describing the overall architecture later.

How should the code be documented? Take this example from the current code:

/*
============
Cvar_Get

If the variable already exists, the value will not be set unless CVAR_ROM
The flags will be or'ed in if the variable exists.
============
*/
cvar_t *Cvar_Get( const char *var_name, const char *var_value, int flags ) {

I'd argue that listing the function name is redundant. When looking for a certain function, you can use the functionality of your IDE. I'd also like to use Doxygen style so we can generate Doxygen documentation. I'd rather have something like this:

/** @brief Create or retrieve a Cvar (Console Variable)

    If the Cvar has to be created but there is no space left, a ERR_FATAL Com_Error() is raised and NULL is returned.
    @param var_name Name of the Cvar to create/retrieve.
    @param var_value Value to use if creating a new Cvar. Ignored if the Cvar exists unless flags contain CVAR_ROM.
    @param flags Various options to enable for this Cvar. If the Cvar already exists, these will be enabled in addition to any other already enabled ones.
    @return Pointer to the requested Cvar, or NULL if no space for Cvars is left.
    @sa CvarFlags
*/

Any comments on that? Do/Don't? Any other wishes/recommendations regarding the documentation? Like a "Where do I need to look for X" list would obviously be nice. Should that kind of stuff go into our wiki? Then it will be missing when people fork. Should a docu/ folder be added? How should that documentation be written? A text-only Doxygen file?

[eezstreet]

I like the idea of using Doxygen. I only ask that you keep the compiled documentation, so that new people won't have to download Doxygen in order to get documentation.

[klusark]

@eezstreet, where would you want the documentation kept? The git repository would be a horrible place for that IMHO.

[deepy]

Given the amount of people with webservers I do not think we'll have any problems finding a place to store it and I believe the documentation could be generated through buildbot (which is being worked on in #68)

[eezstreet]

@joel probably a /doc/ folder on the Github, or stored on an external webserver, and the Documentation link on the wiki linking to it.

Date: Sun, 14 Apr 2013 10:07:41 -0700
From: [email protected]
To: [email protected]
CC: [email protected]
Subject: Re: [OpenJK] Docu style (#109)

Given the amount of people with webservers I do not think we'll have any problems finding a place to store it and I believe the documentation could be generated through buildbot (which is being worked on in #68)

—
Reply to this email directly or view it on GitHub.

[archseer]

The documentation should be stored in a gh-pages orphan branch, which makes them available online via https://razish.github.io/OpenJK/.

It's called Github Pages: https://help.github.com/articles/creating-project-pages-manually

Here's my own example and the orphan gh-pages branch.