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

R2021a 以降

このページをすべて展開する

説明

ルール定義

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

根拠

このルールでは、開発者が外部から可視の宣言をドキュメント化し、宣言された型や関数のユーザーがドキュメントに基づいて想定を立てられるようにする必要があります。

開発者は宣言に先行するコメントで、関数やメソッドの使い方、パラメーターの説明、スローされる例外、その他の仕様 (二次的影響、メモリ管理、所有権など) の情報をドキュメント化することができます。

Polyspace 実装

定義の前に宣言が来る場合は、先行するコメントがない場合にチェッカーがその宣言にフラグを設定します。それ以外の場合は、チェッカーがその定義にフラグを設定します。

宣言または定義と先行するコメントの間には、最大 1 つの空行を挿入できます。

場合によっては、ルールを無効にしたり、一部の違反を正当化する必要があります。次に例を示します。

  • レガシ プロジェクトには、十分にドキュメント化されていない型や関数が多数含まれている場合があります。このようなプロジェクトをクリーンアップしない場合は、このルールの無効化を検討してください。

  • Doxygen などのコード ドキュメンテーション ツールで、データ メンバーやメンバー関数の "後ろ" にドキュメンテーション コメントを追加できます。Doxygen では、コメントの先頭を < にすると、このツールがコメントをデータ メンバーやメンバー関数のドキュメントとして認識します。次に例を示します。

    int var; /*!< Data member description*/
    ただし、Polyspace はそのような宣言や定義をルール違反と見なします。このスタイルのドキュメンテーション コメントの使用を続ける場合は、違反の正当化を検討できます。

トラブルシューティング

ルール違反が想定されるものの、Polyspace® から報告されない場合は、コーディング規約違反が想定どおりに表示されない理由の診断を参照してください。

例

すべて展開する

#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
};

この例では、クラス aClass の定義に 3 つのルール違反が含まれています。クラス定義自体、コンストラクター定義、およびデータ メンバー aVar の定義のすべてに、定義を説明する先行コメントがありません。

クラス anotherClass は、このルールの要件を満たす同じクラスの準拠バージョンです。

チェック情報

グループ: 構文規則
カテゴリ: Required、Automated

バージョン履歴

R2021a で導入

すべて展開する

参考

トピック