I think it would be positive to have an automaticily created documentation from the original objects. This isn't something we need to push yet, but to avoid unneccessary work I would suggest to apply the following documentation guidelines for newly created objects instead the old.

Documentation Guidlines

First, every object should have an description what it is for. This block should be at the beginning of every script.

Example:
/** An cool object.
* This object can do many cool things, for example, beeing cool or letting your clonks getting an cold. Should be used with care.
* @sa VeryCoolObject
* @author Spell
*/

The first line is the summary. Typically it should be only an one liner.
The second line is the detailed description, it should tell what the object and how you typically use it.
@sa is an abreviation of "see also" it adds an paragraph to the documentation saying "See also:" with links to the listed identifiers.
@author let you define an author or an list of authors to the documentation if you want to be named.

Secondly, every identifer (Methods and Variables) can have an documentation, and those which are most likely to be used outside should've an documentation.

Example:
/** Makes \a target freezed.
* @param target The object which shall be freezed.
* @param time The time in frames till \a target will get freed again.
* @return \c true if \a target was sucessfully freezed, \c false otherwise.
*/
public func FreezeClonk(object target, int time)
{
  [...]
}

The first line is the description of the method.
The second and the third lines are the descriptions of the parameters.
The forth line tells what the return value is.
\a, \b and \c are for visual enhencmant, \a makes the next word italic, \b makes it bold and \c makes it proportional. Alternativly Doxygen support HTML Elements like <i>,<b> and <tt> for further formatting.

This are the basics. You can find more informations at in the Doxygen Manual especially in the list of the commands

doxyC4S.py

doxyC4S is an Python-Script which I've written for the creation to beeing able to use Doxygen together with C4Script. To use it you need to put the Script in the directory of your Doxyfile and setting either the INPUT_FILTER value or the FILTER_PATERN value to it. (INPUT_FILTER = doxyC4S.py  or FILTER_PATTERNS = *.c=doxyC4S.py). You can download the script here.

The script has some extra functionality which you may want to use:

Enums
//? Start Enum <Name> says doxyC4S that the following static constants (till the next //? End Enum) should be interpreted as part of the enum.

Example:
/** Damage Types. */
//? Start Enum DMG_Type
static const DMG_Melee=0;
static const DMG_Explosion=1;
static const DMG_Fire=2;
static const DMG_Other=3;
//? End Enum

Doxygen Only Lines
With //?- you can define Lines which are only interpreted by Doxygen but not by Clonk. This is for overiding the declaration of the methods, for example for saying Doxygen that you want an Enum and not really an int as you say clonk.

Example:
/** Returns the resistance of the object to the given \a damageType.*/
//?- public func GetResistance(DMG_Type damageType)
public func GetResistance(int damageType)
{
  [...]
}