CQM-InformalDocumentation

Public routines should be formally documented

Required inputs: IR

Informal documentation is present when a public routine declaration does not use a formal documentation mechanism for its documentation.

Motivation

Source code documentation mechanisms - such as Doxygen - provide a uniform, well-known standard that can be used to document the code and, for example, generate easily readable API documentation in the form of HTML pages. Newer IDEs such as Eclipse can already generate such documentation skeletons automatically. If programmers do not adhere to the specified mechanisms or if no such mechanisms are specified, there can be no manageable, comprehensive documentation that can be edited with tools and is up-to-date.

This rule is based on the CQM Quality Indicator: informelle Dokumentation (p. 222-224).

Reference

Simon, Frank/ Seng, Olaf/ Mohaupt, Thomas (2006): Code-Quality-Management: Technische Qualität industrieller Softwaresysteme transparent und vergleichbar gemacht, 1st ed., Heidelberg, Germany: dpunkt.verlag GmbH.

Possible Messages

Key	Text	Severity	Disabled
missing_doxygen_comment_before_def	No Doxygen comment before definition.	None	False
missing_doxygen_comment_for_def	No Doxygen comment for definition.	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 = True

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 = True

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_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] = {'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.