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

Поддержка