... | ... | @@ -23,14 +23,52 @@ Many of the rules of the [FreeBS kernel style](https://www.freebsd.org/cgi/man.c |
|
|
* Structure and union members documented on the same line if the comment fits. This also applies to non-function non-method class members.
|
|
|
* Use `@return` for describing return values. Usage of `@retval` (or more of them) instead of `@return if the function returns some distinct values (such as 0 for no error, -1 for something else, etc.) is also encouraged.
|
|
|
* We don't use file comments currently.
|
|
|
|
|
|
* Every API function/method must have a comment containing at least:
|
|
|
* a brief description
|
|
|
* parameters (if applicable)
|
|
|
* return values (if applicable)
|
|
|
* Functions and methods are commented upon their declarations in the header files. (The only exceptions are static functions.)
|
|
|
|
|
|
```c
|
|
|
|
|
|
/*!
|
|
|
* @brief Some class.
|
|
|
*
|
|
|
* Longer description.
|
|
|
*/
|
|
|
class SomeClass {
|
|
|
public:
|
|
|
/*!
|
|
|
* @brief Constructor.
|
|
|
*/
|
|
|
SomeClass(void);
|
|
|
|
|
|
...
|
|
|
private:
|
|
|
const QString name; /*!< Some name. */
|
|
|
QByteArray value; /*!<
|
|
|
* This description does not fit on a single line
|
|
|
* because it is rather verbose.
|
|
|
*/
|
|
|
};
|
|
|
|
|
|
/*!
|
|
|
* @brief This is function doing something.
|
|
|
* @brief This is a function doing something.
|
|
|
*
|
|
|
* Longer description of what it really does.
|
|
|
*
|
|
|
* @note Nobody actually knows what it really does.
|
|
|
*
|
|
|
* @warning Use this function at own risk.
|
|
|
*
|
|
|
* @see anotherFunction()
|
|
|
*
|
|
|
* @param[in] par1 Some parameter.
|
|
|
* @param[out] par2 Data to be processed.
|
|
|
* @retval 0 on success
|
|
|
* @retval -1 on any error
|
|
|
*
|
|
|
* @todo Remove (deprecated).
|
|
|
*/
|
|
|
int someFunction(const QString &par1, QByteArray &par2);
|
|
|
``` |
|
|
\ No newline at end of file |