Next Previous Table of Contents
Другая важная часть документации - краткое описание интерфейса классов. Это позволит вам и другим
программистам использовать ваши классы, читая HTML файлы документации классов, которая создается с помощью KDoc
. KDevelop поддерживает использование
KDoc
для создания документации к KDE-библиотекам, и ваш шаблон уже документирован. Для работы
с предлагаемым в нем кодом полезно прочитать online-документацию. Данная глава описывает, что необходимо сделать
для документирования API, и как KDevelop поможет вам в этом, также рассматриваются дополнительные таги, поддерживаемые KDoc
.
Для создания документации API после разработки проекта выберите "Make API-Doc" из меню "Project". Это приведет к просмотру всех файлов заголовков и созданию на их основе HTML файлов документации. После этого вы сможете получить доступ к документации, выбирая "API-Documentation" из меню помощи или соответствующую книгу в дереве документации, папка "Current Project".
Документация уже содержит ссылки на KDE и Qt online-документацию классов, поэтому вы сможете проследить наследование и легко обозреть иерархию. Это может вам также помочь в начале работы с документацией KDE и Qt.
KDevelop предоставляет как способы автоматического добавления кода, так и способы автоматического документирования. Когда вы используете генератор классов, выбирая "Project"->"New Class", добавьте краткое описание класса в поле документирования. Это вставит его в заголовок класса.
При добавлении в класс функции-члена и атрибутов с помощью classtools, добавьте краткое описание члена в поле документирования.
Вы можете подумать, что документация - это часть процесса разработки, которая не очень важна. Но помните, что большинство проектов растут, и все больше и больше людей начинают принимать участие в их разработке. Поэтому документирование классов - хороший путь сэкономить время. Даже если вы присвоили методам имена, точно описывающие их назначение, очень вероятно, что их не поймут или со временем изменятся функции метода. Поэтому поддерживайте в порядке вашу документацию и обновляйте ее как можно чаще.
Несмотря на вышесказанное, файлы документации НЕ включаются в проект, и не интернационализируются. Поэтому вся документация API должна быть написана на английском, чтобы позволить работать с ней международной команде.
Если вы хотите добавить документирование вручную в файл заголовка, добавьте его над методом или классом в виде C-комментария с одним отличием - первая строка должна начинаться со слеша и двух звездочек.
Например:
/** enables menuentries/toolbar items
*/
void enableCommand(int id_);
Внимание: последующий текст этой главы взят из документации 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
см. выше
@ref
Взято из формата документирования java. Метасимвол @ref имеет тот же формат, что и @see, но может встречаться в любом месте документации
(остальные описания должны располагаться на той же строке, что и таг).
Next Previous Table of Contents