0ct0pu5/wesnoth
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Doxygen: Update static doc pages

Browse source
This commit is contained in:
Ignacio R. Morelle 2016-06-22 03:53:31 -04:00
parent 6a25cac78d
commit 6ff5509ec6
1 changed files with 51 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

89
doc/doxygen/doxygen.cpp
View file

@ -292,34 +292,28 @@ the text will also be registered as a tooltip.
@page get_involved Get Involved
Apart from development, there are
<a href="http://www.wesnoth.org/wiki/FAQ">other ways to contribute</a>
to the project.
Before you can join the development team, your work
needs to be reviewed by a current developer.
It works like this:
you first get the latest source code
and then submit your modified source code as
<a href="http://www.kegel.com/academy/opensource.html">patches</a> to
<a href="http://gna.org/patch/?group=wesnoth">Gna!</a>.
Eventually, you may be given repository access.
needs to be reviewed by other developers.
- Clone the <a href="https://wiki.wesnoth.org/WesnothRepository">Git repository</a> to obtain access to the latest source code.
- Read up on our C++ <a href="https://wiki.wesnoth.org/CodingStandards">coding standards</a>.
- Check the <a href="https://wiki.wesnoth.org/PatchSubmissionGuidelines">Patch Submission Guidelines</a> and the <a href="https://wiki.wesnoth.org/DeveloperGuide">Developer Guide</a> for information on best practices for authoring Git commits.
- Submit your pull requests on <a href="https://github.com/wesnoth/wesnoth/">GitHub</a>.
One way to contribute is to find an unassigned bug in the
<a href="http://gna.org/bugs/?group=wesnoth">bug repository</a>
and fix the bug.
<a href="http://gna.org/bugs/?group=wesnoth">bug tracker</a>
and fix it.
If you wish to work on something else, you should probably
explain on the
<a href="http://www.wesnoth.org/forum/">forum</a>
<a href="https://forums.wesnoth.org/">forum</a>
what you wish to do before doing any actual development.
Do make sure you have read the projects
<a href="http://www.wesnoth.org/wiki/CodingStandards">coding standards</a>.
When adding new features, keep in mind the project philosophy,
which is that of
<a href="http://www.wesnoth.org/wiki/WesnothPhilosophy">KISS</a>.
<a href="https://wiki.wesnoth.org/WesnothPhilosophy">KISS</a>.
Other than at the forum, developers may also hang out
in IRC @#wesnoth-dev at irc.freenode.net
The development team hangs out in the IRC channel
<a href="https://webchat.freenode.net/?channels=wesnoth-dev">@#wesnoth-dev on irc.freenode.net</a>.
Feel free to join us and ask any questions you may have about our codebase!
*/
@ -351,8 +345,10 @@ of a few, minor things in order to produce readable
documentation using Doxygen.
The basic guidelines for this project are:
- When commenting part of an interface, use two slashes followed by
an exclamation sign, followed by a space and then the actual comment.
- When commenting part of an interface, use one slash followed by
two asterisks, followed by a line break and then the actual comment
with an asterisk and a space aligned to the first asterisk in the
opening line.
The first sentence you write, terminated by a period,
will be the brief description.
After that, you can write a longer, more detailed description.
@ -363,17 +359,31 @@ The basic guidelines for this project are:
Example:
@code
/ / ! Takes care of displaying the map and game-data on the screen.
/ / !
/ / ! The display is divided into two main sections: the game area,
/ / ! which displays the tiles of the game board, and units on them,
/ / ! and the side bar, which appears on the right hand side.
/ / ! The side bar display is divided into three sections.
class display {
/** Takes care of displaying the map and game-data on the screen.
*
* The display is divided into two main sections: the game area,
* which displays the tiles of the game board, and units on them,
* and the side bar, which appears on the right hand side.
* The side bar display is divided into three sections.
*/
class display
{
...
};
@endcode
- It is also possible to document symbols on the same line by using a slash
followed by two asterisks and a left angular bracket:
@code
enum ADDON_TYPE {
ADDON_SP_CAMPAIGN, /**< Single-player campaign. */
ADDON_SP_SCENARIO, /**< Single-player scenario. */
ADDON_MP_CAMPAIGN, /**< Multiplayer campaign. */
ADDON_MP_SCENARIO, /**< Multiplayer scenario. */
};
@endcode
- Do not refer to multiple objects of the type "Manager"
as "Managers" or "manager". Instead, say "Manager objects".
Doxygen will automatically link to class documentation
@ -382,21 +392,24 @@ class display {
- Many <a href="http://www.stack.nl/~dimitri/doxygen/commands.html">Doxygen commands</a>
can be used in comments to enhance the generated documentation and structure the comments.
- There is a balance between readable autogenerated documentation and readable code,
so beware of overdoing it.
Example:
@code
/ / ! @param a an integer dividend
/ / ! @param b an integer divisor, which must not be zero
/ / ! @returns a / b
/ / !
/ / ! @pre b != 0
/ / ! @post divide' = a / b
/ / !
/ / ! @throws std::runtime_error
/ / ! @todo this has not been peer reviewed yet
int divide(int a,int b) {
/** @param a an integer dividend
* @param b an integer divisor, which must not be zero
* @returns a / b
*
* @pre b != 0
* @post divide' = a / b
*
* @throws std::runtime_error
* @todo this has not been peer reviewed yet
*/
int divide(int a, int b)
{
return a / b;
}
@endcode