Documentation Within the FSO Codebase

Documenting the Code

We use doxygen formatting to document the codebase. The particularly important doxygen keywords are:

• @brief --Optional, but is the default keyword when making a doxy compatible comment
• @details --Use to explain a class or function if the one-line brief is insufficient
• @param -- Documents each of the input parameters to the function. @param[in] for input params, @param[out] for output params, and @param[in/out] for bi-directional
• @note -- Use if there's something you want to bring attention to, clarify, or re-iterate from the @brief or @details
• @warning -- Use if there's something that could cause trouble if a coder is not cautious, such as the possibility of an overflowing array
• @return -- Use to document all possible return values. Get the point across, you don't have to be specific like "@return 1 if the answer is 1, @return 2 if the answer is 2"

Doxygen supports two major styles of documenting, we largely used the C++ style one which uses /**

 /**
  * This is brief example
  *
  * @details Each asterisk in the border lines up with the first asterisk in the first line,
  *   you may format multi-line comments any way you want, but try to retain the style of
  *   previous 'doxy' comments and also try to make the style as clear and consistent as
  *   possible
  *
  * @note Do not use tabs inside of the comment block.  You may use tabs to indent the
  *   comment block, but everything after the first asterisk must be spaces or else
  *   the tabs may mess up the formatting for different users.
  */

Where to doxy:

You should only doxy the declaration of classes, functions, etc. which is usually in a .h file. Local classes and methods that are only used within a .cpp or .c file may be doxy'd at their declaration. You should not doxy the implementation of classes/functions unless the implementation is also the declaration.

This is to provide a consistent place to look for the documentation as well as reduce the time spent scrolling between functions just to see what something does. The .h explains what a class/function does with human readble words, while the .cpp defines what a class/function does with code.

When to doxy:

1. Whenever you're making new code.
2. Whenever you're spading through the codebase and find something that's not documented or poorly documented

Should you PR doxy-only changes?

By all means, YES. The only requirement here is that your git commits should be logically similar. When doing doxy PR's, try to do just that. Don't sneak in any new code, Don't sneak in minor tweaks to the code, even if they are a fix -- do those in another commit and another PR.

Should you doxy code that's unrelated to your work?

No. For example, if you're doing a PR that's working in the AI code, but somehow stumbled across a function that needs doxy from the multi-code, DONT include the doxy to the PR unless it is logically related to your work (as in, the undocumented function/class uses or is used by the functions/classes in your contribution). Instead, you should make a separate PR for the doxy changes.

How detailed should the details be?

As much detail needed to get the general idea of what the function/class does. If a coder needs implementation-specific details of the function/class that's being documented, they should be looking at the documentation in the implementation (the .cpp file)

---

Other documentation:

Sexps (TODO)

LUA scripting (TODO)

FS2 Wiki

All new features and behavior changes to existing features should be documented in the FS2 Wiki so that modders and players can refer to them. Doxygen is for coders, the Scripting.html is for modders, and the sexp documentation is for fredders.