AUTOSAR C++14 Rule A2-7-3

All declarations of "user-defined" types, static and non-static data members, functions and methods shall be preceded by documentation

Since R2021a

expand all in page

Description

Rule Definition

All declarations of "user-defined" types, static and non-static data members, functions and methods shall be preceded by documentation.

Rationale

This rule requires developers to document externally visible declarations so that users of the declared types and functions can form expectations based on this documentation.

In comments preceding the declarations, developers can document information such as function and method usage, parameter descriptions, exceptions thrown, and other specifications such as side effects, memory management and ownership.

Polyspace Implementation

In cases where a declaration comes before a definition, the checker flags the declaration if there are no preceding comments. Otherwise, the checker flags the definition.

There can be at most one blank line between a declaration or definition and the preceding comment.

In some cases, you might want to disable the rule or justify some violations. For instance:

Legacy projects might contain many insufficiently documented types or functions. Unless you want to clean up these projects, you might consider disabling this rule.
In code documentation tools such as Doxygen, you can add documentation comments after a data member or member function. In Doxygen, if you begin the comment with <, the tool considers the comment as documentation for the data member or member function. For instance:
```
int var; /*!< Data member description*/
```
However, Polyspace considers such declarations or definitions as rule violations. If you want to continue using this style of documentation comments, you might consider justifying the violations.

Troubleshooting

If you expect a rule violation but Polyspace^® does not report it, see Diagnose Why Coding Standard Violations Do Not Appear as Expected.

Examples

expand all

Noncompliant and compliant class definitions

#include <cstdint>

class aClass { //Noncompliant class definition
public:
	aClass(std::int32_t aParameter): aVar(aParameter) {} //Noncompliant    
private:
	std::int32_t aVar; //Noncompliant variable definition
};

/// @desc Class responsibilities

class anotherClass { //Compliant class definition
public:
	/// @desc Constructor description
	///
	/// @param aParameter Parameter description
	anotherClass(std::int32_t aParameter): anotherVar(aParameter) {} //Compliant
private:
	/// @desc Data member description
	std::int32_t anotherVar; //Compliant variable definition
};

In this example, the definition of class aClass has three rule violations. The class definition itself, the constructor definition, and the definition of data member aVar are all missing preceding comments explaining the definitions.

The class anotherClass is a compliant version of the same class that satisfies the requirements of this rule.

Check Information

Group: Lexical conventions

Category: Required, Automated

Version History

Introduced in R2021a

expand all

R2024a: Checker correctly interprets comments that precede static data members

The checker no longer reports a violation on declarations of static data members that are preceded by a comment.

R2023b: Checker skips template instances

The checker skips template instances when looking for violations of the rule, and only checks declarations or definitions in the template definition.

R2022b: Checker skips headers included only in suppressed source files

The rule checker shows fewer false positives associated with declarations in headers. Previously, if you suppressed results from a source file using the option Do not generate results for (-do-not-generate-results-for), you might have seen incorrect rule violations in headers included in the source file.

R2022a: Checker no longer flags declarations in local objects if preceded by comments

The rule checker no longer raises a violation on declarations local to an object in a function when they are preceded by a comment. For instance:

// A function
void f1(int i) {
	// A const
	int const N = 20;
	// struct local to f1
	struct s1{
		//int
		int ii = 0; //Compliant
	};
}