Комментарии и документирование
(Created page with "<div style='max-width:700px;text-align:justify;'> {|align="right" |[http://forum.asistech.org/viewforum.php?f=11 Форум] |} Назад | [[Core Java|Ог...") |
|||
Line 1: | Line 1: | ||
<div style='max-width:700px;text-align:justify;'> | <div style='max-width:700px;text-align:justify;'> | ||
− | {| | + | {|style="float:right" |
|[http://forum.asistech.org/viewforum.php?f=11 Форум] | |[http://forum.asistech.org/viewforum.php?f=11 Форум] | ||
|} | |} | ||
Line 297: | Line 297: | ||
---- | ---- | ||
− | {| | + | {|style="float:right" |
|[http://forum.asistech.org/viewforum.php?f=11 Форум] | |[http://forum.asistech.org/viewforum.php?f=11 Форум] | ||
|} | |} | ||
[[Пакеты|Назад]] | [[Core Java|Оглавление]] | [[Рекомендации по разработке классов|Дальше]] | [[Пакеты|Назад]] | [[Core Java|Оглавление]] | [[Рекомендации по разработке классов|Дальше]] | ||
</div> | </div> |
Latest revision as of 20:27, 4 April 2015
Форум |
Назад | Оглавление | Дальше
Contents |
[edit] Комментарии и документирование
Пакет JDK содержит утилиту javadoc, которая использует исходные файлы программы для генерации документации в формате HTML. Фактически описание API является результатом применения утилиты javadoc к исходному коду стандартной библиотеки Java.
Добавляя в программу комментарии, начинающиеся с последовательности символов /**, легко создать документацию, имеющую профессиональный вид. Поскольку комментарии являются неотъемлемой частью исходного файла, документацию легко обновить, повторно выполнив утилиту javadoc.
[edit] Включение комментариев
Утилита javadoc извлекает информацию о следующих элементах:
- Пакеты.
- Классы и интерфейсы, объявленные как public.
- Методы, объявленные как public или protected.
- Поля, объявленные как public или protected.
Модификатор protected и интерфейсы рассматриваются в следующих разделах.
Разрабатывая программу, необходимо комментировать каждый из перечисленных элементов. Комментарии помещаются непосредственно перед элементом, к которому они относятся; начинаются с разделителя /** и заканчиваются символами */.
Комментарии, имеющие вид /** ... */, содержат произвольный текст с дескриптором - tag. Дескриптор начинается символом @, например @author или @param.
Первое предложение текста комментария должно представлять собой краткое описание - summary statement. Утилита javadoc автоматически генерирует страницы, состоящие из кратких описаний
В тексте комментария можно использовать HTML tags, например:
<em> ... </em> // выделение текста курсивом <code> ... </code> // установка моноширинного шрифта <strong> ... </strong> // выделение текста полужирным шрифтом <img ... > // вставка картинки
Не следует использовать тэги:
<h1> - <h6> // заголовки <hr> // горизонтальные линии Эти тэги могут повлиять на форматирование документа!
Если комментарий содержит ссылки на другие файлы, например рисунки, то необходимо поместить эти ресурсы в каталоги, начинающиеся словом doc. Утилита javadoc скопирует эти каталоги из исходного каталога в каталог документации.
[edit] Комментарии к классу
Комментарии к классу должны помещаться после директивы import, непосредственно перед определением класса:
/** * Объект класса <code>Card</code> имитирует игральную карту * Карта имеет масть и ранг * (1=туз, 2...10, 11=валет, 12=дама, 13=король) */ public class Card { ... }
Можно не указывать звездочки в начале каждой строки комментария:
/** Объект класса <code>Card</code> имитирует игральную карту Карта имеет масть и ранг (1=туз, 2...10, 11=валет, 12=дама, 13=король) */
Любая современная среда разработки позволяет настраивать внешний вид комментария.
[edit] Комментарии к методу
Комментарий должен предшествовать методу, который он описывает. Кроме дескрипторов общего назначения можно использовать специальные дескрипторы:
@param переменная описание
Этот дескриптор добавляет в описание метода раздел parameters. Раздел параметров может занимать несколько строк. Также можно использовать HTML. Все дескрипторы @param, относящиеся к одному методу, должны быть сгруппированы вместе.
@return описание
Этот дескриптор добавляет в описание метода раздел returns (возвращаемое значение). Данный раздел также может занимать несколько строк, и позволяет использовать HTML.
@throws описание_класса
Этот дескриптор означает, что метод может генерировать исключение. Исключения рассматриваются в следующих разделах.
Пример комментариев к методу:
/** * Увеличивает зарплату сотрудников. * @param Переменная byPercent содержит величину * в процентах, на которую повышается зарплата * (например, 10 = 10%). * @return Размер повышения */ public double raiseSalary(double byPercent) { double raise = salary * byPercent / 100; salary += raise; return raise; }
[edit] Комментарии к полям
Документировать нужно лишь общедоступные поля - обычно они представляют собой статические константы:
/** * Масть черви */ public static final int HEARTS = 1;
[edit] Комментарии общего характера
В комментариях к классу можно использовать следующие дескрипторы:
@author name // для группы авторов можно использовать несколько таких дескрипторов @version text // где, text - произвольное описание версии
При создании комментариев для документации, можно также использовать следующие дескрипторы:
-
@since text Создает раздел since ("начиная с"), например: @since version 1.7.1
-
@deprecated text Помечает класс, метод или переменную, как не рекомендованные к применению. Обычно, после данного дескриптора следует некоторое выражение: @deprecated Use <code>setVisible(true)</code> instead
-
@see ссылка Ссылка на внешний документ или на позицию в составе текущего документа. Ссылка добавляется в раздел See also ("См. также"). Дескриптор можно использовать в комментариях к классам и методам.
Ссылки условно делятся на три категории:
- пакет.класс#элемент метка
- <a href=" ... ">метка</a>
- "text"
Первый вариант встречается чаще. Здесь нужно указать имена класса, метода или переменной, а утилита javadoc вставит в документацию соответствующую ссылку. Например, приведенная ниже команда создает ссылку на метод raiseSalary(double) класса com.horstmann.corejava.Employee:
@see com.horstmann.corejava.Employee#raiseSalary(double)
Для отделения имени класса от имени метода или переменной нужно использовать символ #, а не точку. Компилятор javac корректно обрабатывает точки, выступающие в качестве разделителей между именами пакетов, подпакетов, классов, внутренних классов, методов и переменных. Однако утилита javadoc не на столько тщательно проработана, поэтому возникает необходимость в специальном синтаксисе.
Если вслед за дескриптором @see стоит символ <, то программист должен указать гипертекстовую ссылку. Ссылаться можно на любой url-адрес, например:@see <a href="www.horstmann.com/corejava.html">Web-страница книги "Основы языка Java"</a>
В каждом случае можно указать необязательную метку, которая играет роль якоря для ссылки. Если метку не указать, то якорем ссылки будет считаться имя кода или url. Если за дескриптором @see стоит символ ", то текст отображается в разделе "see also":
@see "Основы языка Java, том 2"
Для одного и того же элемента можно использовать несколько дескрипторов @see, при этом, их следует сгруппировать вместе.
-
@link Гипертекстовая ссылка на другие классы или методы в любом комментарии. Для перехода следует включить в нужную позицию специальный дескриптор вида: {link пакет.класс#элемент метка} Описание элемента аналогично дескриптору @see
[edit] Комментарии к пакетам и обзоры
Комментарии к классам, методам и переменным помещаются непосредственно в исходных файлах.
При этом комментарии выделяются символами /** ... */.
Для генерации комментариев к пакету, в каталог пакета добавляется файл package.html.
Весь текст, содержащийся между дескрипторами <body> ... </body>, извлекается утилитой javadoc.
Все исходные файлы можно сопроводить обзорными комментариями. Они создаются в файле под названием overview.html, размещенном в родительском каталоге, содержащем все исходные файлы. Аналогично файлу package.html, контент overview.html, находящийся между дескрипторами <body> ... </body>, извлекается утилитой javadoc. Эти комментарии отображаются на экране, когда пользователь выбирает Overview.
[edit] Извлечение комментариев
Предположим, что docDirectory - каталог, в котором расположены HTML-файлы:
- Перейдем в каталог с исходными файлами, подлежащими документированию. Если это вложенные пакеты, например com.horstmann.corejava, нужно перейти в каталог, содержащий подкаталог com. Именно там должен храниться файл overview.html.
-
Для документирования одного пакета, выполним команду:
javadoc -d docDirectory имя_пакета
Для документирования нескольких пакетов, выполним команду:
javadoc -d docDirectory имя_пакета_1 имя_пакета_2 ...
Если файлы находятся в пакете, заданном по умолчанию, вместо приведенных выше команд нужно выполнить следующую:
javadoc -d docDirectory *.java
Если пропустить опцию -d docDirectory, HTML-файлы будут извлечены в текущий каталог, что вызовет путаницу. Лучше этого не делать.
При вызове javadoc можно указывать различные опции, например:
-
-author
Включает в документацию дескриптор @author.
-
-version
Включает в документацию дескриптор @version.
-
-link
Позволяет включать ссылки на стандартные классы. Например, следующая команда автоматически создаст ссылку на документацию, находящуюся на Web-узле Sun:
javadoc -link http://java.sun.com/j2se/5.0/docs/api *.java
Другие опции описаны в документации на javadoc, которую можно найти по адресу: http://java.sun.com/products/jdk/javadoc/index.html
Если требуется более тонкая настройка, например, генерация документации в формате, отличающемся от HTML, то можно разработать собственный doclet, позволяющий создавать документацию произвольного вида. Более подробную информацию о данном подходе можно получить на Web-странице: http://java.sun.com/j2se/javadoc
Доклет DocCheck (http://java.sun.com/j2se/javadoc/doccheck) может оказаться очень полезным для работы. Он просматривает исходные файлы и отмечает пропущенные комментарии.
Форум |
Назад | Оглавление | Дальше