Специальный документационный блок — это блок комментария в стиле C или C++ с добавлением некоторых меток, так doxygen узнает, что это часть документации, которую необходимо добавить в генерируемую документацию. Для Python и кода VHDL существуют другие соглашения о комментированиии, которые можно найти в разделе Специальные документационные блоки для Python и Специальные документационные блоки для VHDL соответственно.

Для каждого элемента кода есть два (или в некоторых случаях три) типа описаний, которые вместе образуют документацию: краткое описание и подробное описание, оба необязательны. Для методов и функций также существует третий тип описания, так называемый описание «в теле», которое содержит объединение всех комментариев найденных в теле метода или функции.

Создавать больше одного краткого или подробного описания возможно (но не рекомендуется, так как порядок в котором они будут отображаться не определен).

Как видно из названия, краткое описание — короткое, однострочное, тогда как подробное описание обеспечивает более длинное и детальное документитрование. Описание «в теле» можно выполнять как детальное описание или может подробно описывать последовательность исполнения. Для вывода в HTML короткие описания также используются для того, чтобы обеспечить подсказки в тех местах, где есть ссылка на этот элемент.

Есть несколько способов отметить блок комментария как подробное описание:

  1. Вы можете использовать стиль JavaDoc, которые состоят из блока комментария в стиле C, начинающийся с двух звездочек (*), как здесь: /** * … текст … */
  2. или вы можете использовать стиль Qt и добавить восклицательный знак (!) после открытия блока комеентария в стиле C, как показано в этом примере: /*! * … текст … */ В обоих случаях промежуточные звездочки * необязательны, так /*! … текст … */ так же правильно.
  3. Третий способ — использовать блоки состоящие из трех и более строк комментария C++, где каждая строка начинается с дополнительного слеша или восклицательного знака. Вот примеры двух случаев: /// /// … текст … /// или //! //!… текст … //! Заметьте, что пустая строка завершает блок документации в этом способе.
  4. Некоторым людям нравится делать блоки комментариев в документации более выделенными. Для этих целей Вы можете использовать следущее: /********************************************//** * … текст ***********************************************/ (отметьте 2 наклонных черты, чтобы закончить обычный блок комментария и начатьспециальный блок). или ///////////////////////////////////////////////// /// … текст … /////////////////////////////////////////////////

Для краткого описания также есть несколько возможностей:

  1. Одна из них — использовать команду \brief с одним из указанных выше блоков комменария. Эти команда завершается конецом абзаца, таким образом, подробное описание следует после пустой строки. Вот пример: /*! \brief Краткое описание. * Краткое описание продолжается. * * Подробное описание начинается здесь. */
  2. Если JAVADOC_AUTOBRIEF установлено в YES в конфигурационном файле, тогда при использовании стиля блоков комментария JavaDoc будет автоматически начинаться краткое описание, которое завершается первой точкой и следующим за ней пробелом или новой строкой. Вот пример: /** Краткое описание, которое заканчивается точкой. Полное начинается * здесь. */ Аналогично многострочный специальный комментарий C++ дает такой же эффект: /// Краткое описание, которое заканчивается точкой. Полное начинается /// здесь.
  3. Третий вариант — использовать специальный стиль комментария C++, который располагается на одной строке. Вот два примера: /// Краткое описание. /** Полное описание. */ or //! Краткое описание. //! Полное описание //! начинается здесь. Обратите внимание на пустую строку в последнем примере, которая обязатльно должна отделять краткое описание от блока с подробным описанием. Для этого случая JAVADOC_AUTOBRIEF должна быть установлена в NO.

Как видите doxygen достаточно гибкий, даже если у Вас сложное подробное описание как в следующем примере:

//! Краткое описание, которое в действительности

//! является подробным описанием, поскольку занимает несколько строк.

/*! Другое подробное описание!

 */

Они будут объединены. Тоже самое произойдет, если описания находятся в различных местах кода! В этом случае, порядок будет зависеть от того, в каком порядке doxygen анализирует код.

Здесь пример документирования части кода C++ с использованием стиля Qt: 

//!  Тестовый класс. 

/*!

  Более детальное описание класса.

*/



class Test

{

  public:





    //! Перечисление.

    /*! Более детальное описание перечисления. */

    enum TEnum { 

                 TVal1, /*!< Значение TVal1. */  

                 TVal2, /*!< Значение TVal2. */  

                 TVal3  /*!< Значение TVal3. */  

               } 



         //! Указатель на тип перечисления.

         /*! Детали. */

         *enumPtr, 

         //! Переменная с типом перечистелия.

         /*! Детали. */

         enumVar;  

    



    //! Конструктор.

    /*!

      Более детальное описание конструктора.

    */

    Test();



    //! Деструктор.



    /*!

      Более детальное описание деструктора.

    */

   ~Test();

    

    //! Обычная функция с двумя аргументами возвращающая целое значение.

    /*!



      \param a целый аргумент.

      \param s константный символьный указатель.

      \return результаты теста

      \sa Test(), ~Test(), testMeToo() and publicVar()

    */

    int testMe(int a,const char *s);

       



    //! Чистая виртуальная функция.

    /*!

      \sa testMe()

      \param c1 первый аргумент.

      \param c2 второй агрумент.

    */



    virtual void testMeToo(char c1,char c2) = 0;

   

    //! Открытая переменная.

    /*!



      Детали.

    */

    int publicVar;

       

    //! Указатель на функцию.

    /*!



      Детали.

    */

    int (*handler)(int a,int b);

};

Щелкните здесь для просмотра документации, которую сгенерирует doxygen.

Однострочные комментарии содержат краткое описание, тогда как многострочные блоки комментария содержат более детальное описание.

Краткие описания включаются в обзор элементов класса, пространства имен или файла и печатаются маленьким наклонным шрифтом (эти описания могут быть скрыты настройками BRIEF_MEMBER_DESC в NO в конфигурационном файле). По умолчанию, краткие описания располагаются первым предложением детального описания (но это может быть изменено установкой тега REPEAT_BRIEF в NO). Оба описания, краткое и детальное, не обязательны для стиля Qt.

По умолчанию, стиль блока документирования JavaDoc приводит тем же результатам, как и документационный блок в стиле Qt. Однако это не соответствует спецификации JavaDoc, где первое предложение документационного блока автоматически обработано как краткое описание. Чтобы включить такое поведение, Вам нужно установить JAVADOC_AUTOBRIEF в YES в конфигурационном файле. Если Вы включили эту опцию и хотите поставить точку в середине предложения, Вы должны поместить обратный слеш и пробел после нее. Вот пример: 

  /** Краткое описание (т.е.\ используется только несколько слов). Дальше следуют детали. */

Здесь тот же самый кусок кода, показанный выше, на этот раз документированный в стиле JavaDoc и JAVADOC_AUTOBRIEF установлен в YES: 

/**

 *  Тестовый класс. Более детальное описание класса.



 */



class Test

{

  public:



    /** 

     * Перечисление.

     * Более детальное описание перечисления.



     */



    enum TEnum { 

          TVal1, /**< Значение TVal1. */  

          TVal2, /**< Значение TVal2. */  

          TVal3  /**< Значение TVal3. */  

         } 

       *enumPtr, /**< Указатель на тип перечисления. Детали. */



       enumVar;  /**< Переменная с типом перечистелия. Детали. */

       

      /**

       * Конструктор.

       * Более детальное описание конструктора.



       */

      Test();



      /**

       * Деструктор.

       * Более детальное описание деструктора.

       */



     ~Test();

    

      /**

       * Обычная функция с двумя аргументами возвращающая целое значение.

       * @param a целый аргумент.

       * @param s константный символьный указатель.

       * @see Test()



       * @see ~Test()

       * @see testMeToo()

       * @see publicVar()

       * @return результаты теста

       */

       int testMe(int a,const char *s);

       



      /**

       * Чистая виртуальная функция.

       * @see testMe()

       * @param c1 первый аргумент.

       * @param c2 второй агрумент.

       */



       virtual void testMeToo(char c1,char c2) = 0;

   

      /** 

       * Открытая переменная.



       * Детали.

       */

       int publicVar;

       

      /**

       * Указатель на функцию.



       * Детали.

       */

       int (*handler)(int a,int b);

};

Щелкните здесь для просмотра документации, которую сгенерирует doxygen.

Точно так же, если Вы хотите, чтобы первое предложение документационного блока в стиле Qt автоматически было обработано как краткое описание, можно установить QT_AUTOBRIEF в YES в конфигурационном файле.

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