Open main menu

Difference between revisions of "Code Formatting Conventions"

(→‎Naming: Elaborate / clarify a bit)
Line 195: Line 195:
There are many ways to mark such comments, but developers are encouraged to use the JavaDoc style:
There are many ways to mark such comments, but developers are encouraged to use the JavaDoc style:


/**
<pre>
  * Move ("warp") the mouse cursor to the specified position in virtual
/**
  * screen coordinates.
* Move ("warp") the mouse cursor to the specified position in virtual
  * @param x            the new x position of the mouse
* screen coordinates.
  * @param y            the new y position of the mouse
* @param x            the new x position of the mouse
  */
* @param y            the new y position of the mouse
virtual void warpMouse(int x, int y) = 0;
*/
(view the generated documentation [http://doxygen.scummvm.org/d9/df4/classOSystem.html#ecab84670def917107d6c1b5ca3b82c3 here]).
virtual void warpMouse(int x, int y) = 0;
</pre>
(See [http://doxygen.scummvm.org/d9/df4/classOSystem.html#ecab84670def917107d6c1b5ca3b82c3 here] for the docs generated from this.)


As shown in the example, documentation blocks also support several special commands such as '''param'''. Those are prefixed with either '''@''' or '''\''', but developers should always use '''@'''.
As shown in the example, documentation blocks also support several special commands such as '''param'''. Those are prefixed with either '''@''' or '''\''', but developers should always use '''@'''.
If you want to add a brief explanation of a variable or function ''after'' its declaration, this is the correct syntax:
<pre>
int16 x; //!< The horizontal part of the point
int16 y; //!< The vertical part of the point
</pre>
(See [http://doxygen.scummvm.org/d7/d66/structCommon_1_1Point.html#2d868735aeaaf391ce9b3df9232c031f here] for the docs generated from this.)


For more information, visit the official documentation:
For more information, visit the official documentation:
* [http://www.stack.nl/~dimitri/doxygen/docblocks.html Documentation blocks].
* [http://www.stack.nl/~dimitri/doxygen/docblocks.html Documentation blocks].
* [http://www.stack.nl/~dimitri/doxygen/commands.html List of available commands].
* [http://www.stack.nl/~dimitri/doxygen/commands.html List of available commands].
1,079

edits