Miscellaneous-DoxygenCommentInHeader

Place Doxygen comments above classes and functions in header files

Required inputs: IR

This rule warns when a class or function declaration does not have a Doxygen comment.

See Also

Rule Miscellaneous-DoxygenCommentAtDefinition is a similar rule that expects the Doxygen comments above the definitions instead of the declarations.

Possible Messages

Key	Text	Severity	Disabled
missing_doxygen_comment_before_def	No Doxygen comment before declaration.	None	False

Options

• This rule shares the following common options: 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

If true, violations are extended with the comment lines that disqualified as Doxygen comments.

 

allow_inherited

allow_inherited : bool = False

If true, a definition does not need documentation, if a corresponding declaration is documented. This includes definitions of virtual member function.

 

allow_missing_documentation_on_private

allow_missing_documentation_on_private : bool = False

If true, a class-member definition does not need documentation, if it is private.

 

allow_missing_documentation_on_protected

allow_missing_documentation_on_protected : bool = False

If true, a class-member definition does not need documentation, if it is protected.

 

doxygen_start

doxygen_start : set[str] = {'/**', '///'}

Start of a valid Doxygen comment.

 

doxygen_trailer

doxygen_trailer : set[str] = set()

Strings, usually just {'///<'}, 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

If true, defaulted function declarations are not checked for comments.

 

ignore_deleted

ignore_deleted : bool = False

If true, deleted function declarations are not checked for comments.

 

ignore_out_of_template_method_definitions

ignore_out_of_template_method_definitions : bool = False

Whether definitions of template class member functions should be accepted without a comment if the definition is outside the template class

 

ignore_redefinitions

ignore_redefinitions : bool = False

If true, method redefinitions are not checked as they can 'inherit' the comment from the redefined method.

 

ignore_tool_comments

ignore_tool_comments : bauhaus.analysis.config.SearchPattern | None = None

An optional regular expression. Comments where this regex finds a matching substring are ignored in the search for a doxygen comment (e.g. control-comments of other tools).

 

lines_after

lines_after : int = 2

Expect a Doxygen trailing comment by looking at most these many lines that are following.

 

lines_before

lines_before : int = 4

Expect a Doxygen comment by looking at most these many lines up.

 

node_types

node_types : set[bauhaus.ir.PIR_Class_Name] = {'Composite_Type_Interface', 'Routine_Declaration', 'Routine_Definition'}

IR node types to check for preceding Doxygen comment.

 

stop_tokens

stop_tokens : set[str] = {'#define', '#include', ';', '{', '}'}

When searching upwards or downwards for comment tokens, the search will stop when encountering one of these stop tokens. The semicolon is special when searching downwards as the search will not stop for the first semicolon that i.e. ends a block. Without #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.