Topic: Teeworlds {Code} Documentation
Hello dear communitee/s,
as teeworlds will maybe get a wider range of popularity due to the publication on steam,
I'd really like to see a better documentation about teeworlds itself as well as about the actual code, so that people get interested in playing with some changes in the code and maybe even use teeworlds as a base for learning c++ and/or c.
As there are a lot of capable coders in this community, I'd really love if lots of you could participate in order to improve the documentation.
As teeworlds mostly consists of three great parts: The map editor, the server and the client, the documentation should be split in these mayor categories.
Because lots of developers are rather specialised on either the server side or the client side or a few on the editor part, it's preferable that everyone with experience in his own category would choose it in his participation.
Furthermore, you needn't explain and describe everything you already did with whatever code is already vanilla teeworlds,
just pick an object from your category and explain what that object does, how it's arguments are filled and what it's functions/methods do, maybe what it is used for or even a small example.
Of course there are not only functions/methods that are bound to object.
For those you could also write a little explanation.
Those are of course only suggestions for those who would like to participate and help creating a kind of code wiki/ documentation.
Small basic overview of the teeworlds code, thanks to unsigned* char. Created with doxygen.
http://uptee.net/documentation/index.html
This is a documentation about how to add comments into the code in order for it to be parsed correctly as the documentation of the code:
The next part would be for the developers to add some commented documentation pull requests on github which follow the documentation syntax of doxygen.
There are several ways to mark a comment block as a detailed description:
You can use the JavaDoc style, which consist of a C-style comment block starting with two *'s, like this:
/**
* ... text ...
*/For the brief description there are also several possibilities:
One could use the \brief command with one of the above comment blocks. This command ends at the end of a paragraph, so the detailed description follows after an empty line.
Here is an example:
/** \brief Brief description.
* Brief description continued.
*
* Detailed description starts here.
*/If JAVADOC_AUTOBRIEF is set to YES in the configuration file, then using JavaDoc style comment blocks will automatically start a brief description which ends at the first dot followed by a space or new line. Here is an example:
/** Brief description which ends at this dot. Details follow
* here.
*/Putting documentation after members
If you want to document the members of a file, struct, union, class, or enum, it is sometimes desired to place the documentation block after the member instead of before. For this purpose you have to put an additional < marker in the comment block. Note that this also works for the parameters of a function.
Here are some examples:
int var; /**< Detailed description after the member */Most often one only wants to put a brief description after a member. This is done as follows:
int var; //!< Brief description after the memberor
int var; ///< Brief description after the memberFor functions one can use the @param command to document the parameters and then use [in], [out], [in,out] to document the direction. For inline documentation this is also possible by starting with the direction attribute, e.g.
void foo(int v /**< [in] docs for input parameter v. */);Note that these blocks have the same structure and meaning as the special comment blocks in the previous section only the < indicates that the member is located in front of the block instead of after the block.
Here is an example of the use of these comment blocks:
/*! A test class */
class Test
{
public:
/** An enum type.
* The documentation block cannot be put after the enum!
*/
enum EnumType
{
int EVal1, /**< enum value 1 */
int EVal2 /**< enum value 2 */
};
void member(); //!< a member function.
protected:
int value; /*!< an integer value */
};For further and more detailed documentation:
http://www.stack.nl/~dimitri/doxygen/ma … locks.html
Thanks for your attention 
