Комментарии и документирование

From AsIsWiki
Revision as of 11:52, 4 April 2015 by Alex (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Форум

Назад | Оглавление | Дальше


Contents

Комментарии и документирование

Пакет JDK содержит утилиту javadoc, которая использует исходные файлы программы для генерации документации в формате HTML. Фактически описание API является результатом применения утилиты javadoc к исходному коду стандартной библиотеки Java.

Добавляя в программу комментарии, начинающиеся с последовательности символов /**, легко создать документацию, имеющую профессиональный вид. Поскольку комментарии являются неотъемлемой частью исходного файла, документацию легко обновить, повторно выполнив утилиту javadoc.


Включение комментариев

Утилита 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 скопирует эти каталоги из исходного каталога в каталог документации.


Комментарии к классу

Комментарии к классу должны помещаться после директивы import, непосредственно перед определением класса:

/**
 * Объект класса <code>Card</code> имитирует игральную карту
 * Карта имеет масть и ранг
 * (1=туз, 2...10, 11=валет, 12=дама, 13=король)
 */

public class Card {
    ...
}

Можно не указывать звездочки в начале каждой строки комментария:

/**
   Объект класса <code>Card</code> имитирует игральную карту
   Карта имеет масть и ранг
   (1=туз, 2...10, 11=валет, 12=дама, 13=король)
 */

Любая современная среда разработки позволяет настраивать внешний вид комментария.


Комментарии к методу

Комментарий должен предшествовать методу, который он описывает. Кроме дескрипторов общего назначения можно использовать специальные дескрипторы:

@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;
}


Комментарии к полям

Документировать нужно лишь общедоступные поля - обычно они представляют собой статические константы:

/**
 * Масть черви
 */
public static final int HEARTS = 1;


Комментарии общего характера

В комментариях к классу можно использовать следующие дескрипторы:

@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 ("См. также").
    Дескриптор можно использовать в комментариях к классам и методам.
    

    Ссылки условно делятся на три категории:

    1. пакет.класс#элемент метка
    2. <a href=" ... ">метка</a>
    3. "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
    


Комментарии к пакетам и обзоры

Комментарии к классам, методам и переменным помещаются непосредственно в исходных файлах.
При этом комментарии выделяются символами /** ... */.

Для генерации комментариев к пакету, в каталог пакета добавляется файл package.html.
Весь текст, содержащийся между дескрипторами <body> ... </body>, извлекается утилитой javadoc.

Все исходные файлы можно сопроводить обзорными комментариями. Они создаются в файле под названием overview.html, размещенном в родительском каталоге, содержащем все исходные файлы. Аналогично файлу package.html, контент overview.html, находящийся между дескрипторами <body> ... </body>, извлекается утилитой javadoc. Эти комментарии отображаются на экране, когда пользователь выбирает Overview.


Извлечение комментариев

Предположим, что 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) может оказаться очень полезным для работы. Он просматривает исходные файлы и отмечает пропущенные комментарии.



Форум

Назад | Оглавление | Дальше

Personal tools
Namespaces

Variants
Actions
Navigation
Tools