Commit 3cc9f150 authored by Dominik Charousset's avatar Dominik Charousset

Update style guide with new Doxygen style

parent 8b3d9b43
...@@ -16,44 +16,45 @@ Example for the Impatient ...@@ -16,44 +16,45 @@ Example for the Impatient
namespace caf { namespace caf {
namespace example { namespace example {
/**
* This class is only being used as style guide example.
*/
class my_class { class my_class {
public: public:
/** /**
* @brief Constructs `my_class`. * Brief description. More description. Note that CAF uses the
* * "JavaDoc-style" autobrief option, i.e., everything up until the
* The class is only being used as style guide example. * first dot is the brief description.
*/ */
my_class(); my_class();
/** /**
* @brief Destructs `my_class`. * Destructs `my_class`. Please use Markdown in comments.
*/ */
~my_class(); ~my_class();
// do not use the @return if you start the brief description with "Returns"
/** /**
* @brief Gets the name of this instance. * Returns the name of this instance.
* Some more brief description.
*
* Long description goes here.
*/ */
inline const std::string& name() const { inline const std::string& name() const {
return m_name; return m_name;
} }
/** /**
* @brief Sets the name of this instance. * Sets the name of this instance.
*/ */
inline void name(std::string new_name) { inline void name(std::string new_name) {
m_name = std::move(new_name); m_name = std::move(new_name);
} }
/** /**
* @brief Prints the name to `STDIN`. * Prints the name to `STDIN`.
*/ */
void print_name() const; void print_name() const;
/** /**
* @brief Does something. Maybe. * Does something (maybe).
*/ */
void do_something(); void do_something();
...@@ -177,7 +178,8 @@ General rules ...@@ -177,7 +178,8 @@ General rules
#include "caf/example/myclass.hpp" #include "caf/example/myclass.hpp"
``` ```
- When declaring a function, the order of parameters is: inputs, then outputs. - When declaring a function, the order of parameters is: outputs, then inputs.
This follows the parameter order from the STL.
- Never use C-style casts. - Never use C-style casts.
...@@ -225,11 +227,10 @@ Headers ...@@ -225,11 +227,10 @@ Headers
Exceptions to this rule are unit tests and `main.cpp` files. Exceptions to this rule are unit tests and `main.cpp` files.
- Each class has its own pair of header and implementation - Each class has its own pair of header and implementation
files and the relative path is derived from its full name. files and the relative path for the header file is derived from its full name.
For example, the header file for `caf::example::my_class` of `libcaf_example` For example, the header file for `caf::example::my_class` of `libcaf_example`
is located at `libcaf_example/caf/example/my_class.hpp`. is located at `libcaf_example/caf/example/my_class.hpp` and the
Source files simply belong to the `src` folder of the component, e.g., source file at `libcaf_example/src/my_class.cpp`.
`libcaf_example/src/my_class.cpp`.
- All header files should use `#define` guards to prevent multiple inclusion. - All header files should use `#define` guards to prevent multiple inclusion.
The symbol name is `<RELATIVE>_<PATH>_<TO>_<FILE>_HPP`. The symbol name is `<RELATIVE>_<PATH>_<TO>_<FILE>_HPP`.
...@@ -239,7 +240,7 @@ Headers ...@@ -239,7 +240,7 @@ Headers
- Each library component must provide a `fwd.hpp` header providing forward - Each library component must provide a `fwd.hpp` header providing forward
declartations for all types used in the user API. declartations for all types used in the user API.
- Each library component must provide an `all.hpp` header that contains - Each library component must provide an `all.hpp` header that contains the
main page for the documentation and includes all headers for the user API. main page for the documentation and includes all headers for the user API.
- Use `inline` for small functions (rule of thumb: 10 lines or less). - Use `inline` for small functions (rule of thumb: 10 lines or less).
...@@ -275,9 +276,9 @@ extra rules for formatting metaprogramming code. ...@@ -275,9 +276,9 @@ extra rules for formatting metaprogramming code.
// think of it as the following (not valid C++): // think of it as the following (not valid C++):
auto optional_result_type = auto optional_result_type =
conditional { conditional {
if (result_type == void) if result_type == void
then (bool) then bool
else (optional<result_type>) else optional<result_type>
}; };
``` ```
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment