Exponenta Banner
exponenta event banner

Правило AUTOSAR C++ 14 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

Поддержка