Changes

Jump to navigation Jump to search

Code Formatting Conventions

1,400 bytes added, 18:11, 4 April 2008
→‎Special comments: Added entry about doxygen comments
== Special comments ==
=== Special Keywords === The following goes slightly beyond code formatting: We use certain keywords (together with an explanatory text) to mark certains certain sections of our code. In particular:* '''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].
67

edits

Navigation menu