Exponenta Banner

AUTOSAR C++14 Rule A2-7-3

Всем объявлениям «определяемых пользователем» типов, статических и нестатических представителей данных, функций и методов должна предшествовать документация

развернуть все на странице

Описание

Определение правила

Всем объявлениям «определяемых пользователем» типов, статических и нестатических представителей данных, функций и методов должна предшествовать документация.

Объяснение

Это правило требует, чтобы разработчики документировали внешне видимые объявления, чтобы пользователи заявленных типов и функций могли формировать ожидания на основе этой документации.

В комментариях, предшествующих объявлениям, разработчики могут документировать такую информацию, как использование функции и метода, описание параметров, выданные исключения и другие спецификации, такие как побочные эффекты, управление памятью и владение.

Реализация Polyspace

В случаях, когда заявление приходит перед определением, чекер помечает объявление, если нет предыдущих комментариев. В противном случае чекер помечает определение.

Между объявлением или определением и предыдущим комментарием может быть не более одной пустой линии.

В некоторых случаях можно хотеть отключить правило или обосновать некоторые нарушения. Для образца:

  • Устаревшие проекты могут содержать много недостаточно задокументированных типов или функций. Если вы не хотите очистить эти проекты, можно рассмотреть возможность отключения этого правила.

  • В инструментах документации кода, таких как Doxygen, можно добавить комментарии к документации после представителя данных или функции представителя. В Doxygen, если вы начинаете комментарий с <инструмент рассматривает комментарий как документацию для представителя данных или функции представителя. Для образца:

    int var; /*!< Data member description*/
    Однако 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 имеет три нарушения правил. Само определение класса, определение конструктора и определение представителя данных aVar все отсутствующие предыдущие комментарии, объясняющие определения.

Класс anotherClass является совместимой версией того же класса, которая удовлетворяет требованиям этого правила.

Проверяйте информацию

Группа: Лексические конвенции
Категория: Необходимый, Автоматизированный

См. также

Темы

Введенный в R2021a

Документация Polyspace Bug Finder

Поддержка