Difference between revisions of "Code Formatting Conventions"

Code Formatting Conventions (view source)

Revision as of 16:11, 4 April 2008

1,400 bytes added , 16:11, 4 April 2008

→‎Special comments: Added entry about doxygen comments

Salty-horse

68

edits

@@ Line 136: / Line 136: @@
 == Special comments ==
-The following goes slightly beyond code formatting: We use certain keywords (together with an explanatory text) to mark certains sections of our code. In particular:
+=== Special Keywords ===
-* FIXME marks code that contains hacks or bad temporary workarounds, things that really should be revised at a later point.
-* TODO marks incomplete code, or things that could be done better but are left for the future.
+The following goes slightly beyond code formatting: We use certain keywords (together with an explanatory text) to mark certain sections of our code. In particular:
-* WORKAROUND marks code that works around bugs in the original game, like script bugs. Sometimes these bugs worked in the original due to bugs in the original engine, sometimes the bug was visible in the original, too. It's important that you explain here what exactly you work around, and if applicable, refer to relevant tracker items!
+* '''FIXME''' marks code that contains hacks or bad temporary workarounds, things that really should be revised at a later point.
+* '''TODO''' marks incomplete code, or things that could be done better but are left for the future.
+* '''WORKAROUND''' marks code that works around bugs in the original game, like script bugs. Sometimes these bugs worked in the original due to bugs in the original engine, sometimes the bug was visible in the original, too. It's important that you explain here what exactly you work around, and if applicable, refer to relevant tracker items!
+=== Doxygen documentation comments ===
+ScummVM uses the [http://www.doxygen.org/ Doxygen] software to generate HTML documentation for the codebase (available [http://scummvm.org/docs/doxygen/html/index.php here]).
+Doxygen supports ''documentation blocks''. These are specially-formatted comments that doxygen prints out in the generated documentation. They are similar in purpose to Java's Javadoc or Python's docstrings.
+There are many ways to mark such comments, but developers are encouraged to use only this method — a C-style comment block starting with two *'s:
+ /**
+  * Move ("warp") the mouse cursor to the specified position in virtual
+  * screen coordinates.
+  * @param x             the new x position of the mouse
+  * @param y             the new x position of the mouse
+  */
+ virtual void warpMouse(int x, int y) = 0;
+(view the generated documentation [http://scummvm.org/docs/doxygen/html/classOSystem.php#z7_1 here]).
+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 '''@'''.
+For more information, visit the official documentation:
+* [http://www.stack.nl/~dimitri/doxygen/docblocks.html Documentation blocks].
+* [http://www.stack.nl/~dimitri/doxygen/commands.html List of available commands].