AutosarC++17_10-A2.8.3¶
All declarations of “user-defined” types, static and non-static data members, functions and methods shall be preceded by documentation using “///” comments and “@tag” tags
Required inputs: IR
| Level | required |
|---|---|
| Target | implementation |
| Enforcement | automated |
Rationale
Every declaration needs to provide a proper documentation.
This is compatible with the C++ standard library documentation. This forces a programmer to provide a clarification for defined types and its data members responsibilities, methods and functions usage, their inputs and outputs specification (e.g. memory management, ownership, valid boundaries), and exceptions that could be thrown.
Note that the documentation style is also supported by external tools, e.g. doxygen.
Example
//% $Id: A2-8-3.hpp 289445 2017-10-04 11:05:16Z michal.szczepankiewicz $
#include <cstdint>
void F1(std::int32_t) noexcept; // Non-compliant documentation
std::int32_t F2(std::int16_t input1,
std::int32_t input2); // Non-compliant documentation
/// @brief Function description
///
/// @param input1 input1 parameter description
/// @param input2 input2 parameter description
/// @throw std::runtime_error conditions to runtime_error occur
///
/// @return return value description
std::int32_t F3(std::int16_t input1,
std::int16_t input2) noexcept(false); // Compliant documentation
/// @brief Class responsibility
class C // Compliant documentation
{
public:
/// @brief Constructor description
///
/// @param input1 input1 parameter description
/// @param input2 input2 parameter description
C(std::int32_t input1, float input2) : x{input1}, y{input2} {}
/// @brief Method description
///
/// @return return value descrption
std::int32_t const *GetX() const noexcept { return &x; }
private:
/// @brief Data member descpription
std::int32_t x;
/// @brief Data member descpription
float y;
};
See Also
- none
Possible Messages
Key |
Text |
Severity |
Disabled |
|---|---|---|---|
missing_doxygen_comment_before_def |
No Doxygen comment before declaration. |
None |
False |
missing_doxygen_comment_for_def |
No Doxygen comment for definition. |
None |
False |
Options¶
This rule shares the following common options: confidence, exclude_in_macros, exclude_messages_in_system_headers, excludes, extend_exclude_to_macro_invocations, includes, justification_checker, languages, post_processing, provider, report_at, severity
The following places define options that affect this rule: Stylechecks, Analysis-GlobalOptions
add_extra_info¶
add_extra_info : bool = False
allow_inherited¶
allow_inherited : bool = False
allow_missing_documentation_on_private¶
allow_missing_documentation_on_private : bool = False
private.
allow_missing_documentation_on_protected¶
allow_missing_documentation_on_protected : bool = False
protected.
doxygen_start¶
doxygen_start : set[str] = {'/**', '///'}
doxygen_trailer¶
doxygen_trailer : set[str] = set()
{'///<'}, that indicate trailing Doxygen
comments.
If this set is not empty, also trailing comments are accepted and leading comments
must not look like trailing Doxygen comments.
ignore_defaulted¶
ignore_defaulted : bool = False
ignore_deleted¶
ignore_deleted : bool = False
ignore_redefinitions¶
ignore_redefinitions : bool = False
ignore_tool_comments¶
ignore_tool_comments : bauhaus.analysis.config.SearchPattern | None = None
lines_after¶
lines_after : int = 2
lines_before¶
lines_before : int = 4
node_types¶
node_types : set[bauhaus.ir.PIR_Class_Name] = {'Field_Definition', 'Named_Type_Definition', 'Routine_Declaration', 'Routine_Definition'}
stop_tokens¶
stop_tokens : set[str] = {'#define', '#include', ';', '{', '}'}
#include as stop token, leading comments in a file have
been frequently mistaken as comments of the first definition. The former default
value did not include #include. Other sensible stop tokens may be
#pragma, #if, #idef, #ifndef and
#endif.