The K Desktop Environment

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

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

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

Next Previous Table of Contents