Next Previous Table of Contents

### 10. Документирование классов с помощью KDoc

Другая важная часть документации - краткое описание интерфейса классов. Это позволит вам и другим программистам использовать ваши классы, читая HTML файлы документации классов, которая создается с помощью `KDoc`. KDevelop поддерживает использование `KDoc` для создания документации к KDE-библиотекам, и ваш шаблон уже документирован. Для работы с предлагаемым в нем кодом полезно прочитать online-документацию. Данная глава описывает, что необходимо сделать для документирования API, и как KDevelop поможет вам в этом, также рассматриваются дополнительные таги, поддерживаемые `KDoc`.

### 10.1 Как использовать возможности KDevelop по документированию

Для создания документации API после разработки проекта выберите "Make API-Doc" из меню "Project". Это приведет к просмотру всех файлов заголовков и созданию на их основе HTML файлов документации. После этого вы сможете получить доступ к документации, выбирая "API-Documentation" из меню помощи или соответствующую книгу в дереве документации, папка "Current Project".

Документация уже содержит ссылки на KDE и Qt online-документацию классов, поэтому вы сможете проследить наследование и легко обозреть иерархию. Это может вам также помочь в начале работы с документацией KDE и Qt.

### 10.2 Добавление документации классов и их членов

KDevelop предоставляет как способы автоматического добавления кода, так и способы автоматического документирования. Когда вы используете генератор классов, выбирая "Project"->"New Class", добавьте краткое описание класса в поле документирования. Это вставит его в заголовок класса.

При добавлении в класс функции-члена и атрибутов с помощью classtools, добавьте краткое описание члена в поле документирования.

Вы можете подумать, что документация - это часть процесса разработки, которая не очень важна. Но помните, что большинство проектов растут, и все больше и больше людей начинают принимать участие в их разработке. Поэтому документирование классов - хороший путь сэкономить время. Даже если вы присвоили методам имена, точно описывающие их назначение, очень вероятно, что их не поймут или со временем изменятся функции метода. Поэтому поддерживайте в порядке вашу документацию и обновляйте ее как можно чаще.

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

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

Например:

> `

>       /** enables menuentries/toolbar items
>             */
>       void enableCommand(int id_);

> `

### 10.3 Специальные таги

Внимание: последующий текст этой главы взят из документации KDoc, поставляемой вместе с KDoc и написанной Sirtaj S. Kang taj@.kde.org), автором KDoc; Copyright (c) 1997

Документация состоит из:

- Обычного текста. Параграфы должны быть разделены минимум одной пустой строкой.
- Текста в форме

      <pre>
      .....фрагмент кода....
      </pre>

- Различных тагов в форме:

  > `

  >     @имя_тага [параметры тага]

  > `

Доступные таги для каждого объекта кода следующие:

- Классы

  > `

  >       @short [одна фраза текста]
  >         Краткое описание класса
  >       @author [одна фраза текста]
  >         Автор класса
  >       @version [одна фраза текста]
  >         Версия класса (Я обычно устанавливаю это равным RCS/CVS "Id" тага)
  >       @see [одна или несколько ссылок на классы и методы]
  >         Ссылки на связанную документацию.

  > `

- Методы

  > `

  >       @see
  >         см. выше
  >       @return [одна фраза текста]
  >         Фраза, описывающая возвращаемое значение
  >       @param [идентификатор имени параметра] [описание параметра]
  >         Описывает параметр. Может содержать несколько строк и прерывается
  >         пустой строкой, окончанием комментария или другим тагом параметра.
  >         Поэтому обычно располагается в конце комментариев.

  > `

- Константы, множества, свойства

  > `

  >       @see
  >         см. выше

  > `

- ALSO `@ref` Взято из формата документирования java. Метасимвол @ref имеет тот же формат, что и @see, но может встречаться в любом месте документации (остальные описания должны располагаться на той же строке, что и таг).

Next Previous Table of Contents