Documentation in java project

Java — Documentation Comments

The compiler ignores everything from // to the end of the line.

This is a documentation comment and in general its called doc comment. The JDK javadoc tool uses doc comments when preparing automatically generated documentation.

This chapter is all about explaining Javadoc. We will see how we can make use of Javadoc to generate useful documentation for Java code.

What is Javadoc?

Javadoc is a tool which comes with JDK and it is used for generating Java code documentation in HTML format from Java source code, which requires documentation in a predefined format.

Following is a simple example where the lines inside /*….*/ are Java multi-line comments. Similarly, the line which preceeds // is Java single-line comment.

Example

/** * The HelloWorld program implements an application that * simply displays "Hello World!" to the standard output. * * @author Zara Ali * @version 1.0 * @since 2014-03-31 */ public class HelloWorld < public static void main(String[] args) < // Prints Hello, World! on standard output. System.out.println("Hello World!"); >>

You can include required HTML tags inside the description part. For instance, the following example makes use of

.

for heading and

has been used for creating paragraph break −

Example

/** * 

Hello, World!

* The HelloWorld program implements an application that * simply displays "Hello World!" to the standard output. *

* Giving proper comments in your program makes it more * user friendly and it is assumed as a high quality code. * * * @author Zara Ali * @version 1.0 * @since 2014-03-31 */ public class HelloWorld < public static void main(String[] args) < // Prints Hello, World! on standard output. System.out.println("Hello World!"); >>

The javadoc Tags

The javadoc tool recognizes the following tags −

Tag Description Syntax
@author Adds the author of a class. @author name-text
Displays text in code font without interpreting the text as HTML markup or nested javadoc tags.
Represents the relative path to the generated document’s root directory from any generated page.
@deprecated Adds a comment indicating that this API should no longer be used. @deprecated deprecatedtext
@exception Adds a Throws subheading to the generated documentation, with the classname and description text. @exception class-name description
Inherits a comment from the nearest inheritable class or implementable interface. Inherits a comment from the immediate surperclass.
Inserts an in-line link with the visible text label that points to the documentation for the specified package, class, or member name of a referenced class.
Identical to , except the link’s label is displayed in plain text than code font.
@param Adds a parameter with the specified parameter-name followed by the specified description to the «Parameters» section. @param parameter-name description
@return Adds a «Returns» section with the description text. @return description
@see Adds a «See Also» heading with a link or text entry that points to reference. @see reference
@serial Used in the doc comment for a default serializable field. @serial field-description | include | exclude
@serialData Documents the data written by the writeObject( ) or writeExternal( ) methods. @serialData data-description
@serialField Documents an ObjectStreamField component. @serialField field-name field-type field-description
@since Adds a «Since» heading with the specified since-text to the generated documentation. @since release
@throws The @throws and @exception tags are synonyms. @throws class-name description
When is used in the doc comment of a static field, it displays the value of that constant.
@version Adds a «Version» subheading with the specified version-text to the generated docs when the -version option is used. @version version-text

Example

Following program uses few of the important tags available for documentation comments. You can make use of other tags based on your requirements.

The documentation about the AddNum class will be produced in HTML file AddNum.html but at the same time a master file with a name index.html will also be created.

import java.io.*; /** * 

Add Two Numbers!

* The AddNum program implements an application that * simply adds two given integer numbers and Prints * the output on the screen. *

* Note: Giving proper comments in your program makes it more * user friendly and it is assumed as a high quality code. * * @author Zara Ali * @version 1.0 * @since 2014-03-31 */ public class AddNum < /** * This method is used to add two integers. This is * a the simplest form of a class method, just to * show the usage of various javadoc Tags. * @param numA This is the first paramter to addNum method * @param numB This is the second parameter to addNum method * @return int This returns sum of numA and numB. */ public int addNum(int numA, int numB) < return numA + numB; >/** * This is the main method which makes use of addNum method. * @param args Unused. * @return Nothing. * @exception IOException On input error. * @see IOException */ public static void main(String args[]) throws IOException < AddNum obj = new AddNum(); int sum = obj.addNum(10, 20); System.out.println("Sum of 10 and 20 is :" + sum); >>

Now, process the above AddNum.java file using javadoc utility as follows −

$ javadoc AddNum.java Loading source file AddNum.java. Constructing Javadoc information. Standard Doclet version 1.7.0_51 Building tree for all the packages and classes. Generating /AddNum.html. AddNum.java:36: warning - @return tag cannot be used in method with void return type. Generating /package-frame.html. Generating /package-summary.html. Generating /package-tree.html. Generating /constant-values.html. Building index for all the packages and classes. Generating /overview-tree.html. Generating /index-all.html. Generating /deprecated-list.html. Building index for all classes. Generating /allclasses-frame.html. Generating /allclasses-noframe.html. Generating /index.html. Generating /help-doc.html. 1 warning $

Источник

Документирование javadoc

При документировании приложения необходима также поддержка документации программы. Если документация и код разделены, то непроизвольно создаются сложности, связанные с необходимостью внесения изменений в соответствующие разделы сопроводительной документации при изменении программного кода.

Как правило, все существующие среды разработки IDE приложений Java предлагают решение по связыванию кода с документацией в процессе разработки с использованием javadoc. Для этого необходимо соответствующим образом написать комментарий к коду, т.е. документировать. Java комментарии необходимы как для комментирования программы, так и для составления или оформления документации.

Разработан специальный синтаксис для оформления документации в виде комментариев и инструмент для создания из комментариев документации. Этим инструментом является javadoc, который обрабатывая файл с исходным текстом программы, выделяет помеченную документацию из комментариев и связывает с именами соответствующих классов, методов и полей. Таким образом, при минимальных усилиях создания комментариев к коду, можно получить хорошую документацию к программе.

javadoc — это генератор документации в HTML-формате из комментариев исходного кода Java и определяет стандарт для документирования классов Java. Для создания доклетов и тэглетов, которые позволяют программисту анализировать структуру Java-приложения, javadoc также предоставляет API. В каждом случае комментарий должен находиться перед документируемым элементом.

При написании комментариев к кодам Java используют три типа комментариев :

// однострочный комментарий; /* многострочный комментарий */ /** комментирование документации */

С помощью утилиты javadoc, входящей в состав JDK, комментарий документации можно извлекать и помещать в НТМL файл. Утилита javadoc позволяет вставлять HTML тэги и использовать специальные ярлыки (дескрипторы) документирования. НТМL тэги заголовков не используют, чтобы не нарушать стиль файла, сформированного утилитой.

Дескрипторы javadoc, начинающиеся со знака @, называются автономными и должны помещаться с начала строки комментария (лидирующий символ * игнорируется). Дескрипторы, начинающиеся с фигурной скобки, например , называются встроенными и могут применяться внутри описания.

Комментарии документации применяют для документирования классов, интерфейсов, полей (переменных), конструкторов и методов. В каждом случае комментарий должен находиться перед документируемым элементом.

javadoc дескрипторы : @author, @version, @since, @see, @param, @return

Дескриптор Применение Описание
@author Класс, интерфейс Автор
@version Класс, интерфейс Версия. Не более одного дескриптора на класс
@since Класс, интерфейс, поле, метод Указывает, с какой версии доступно
@see Класс, интерфейс, поле, метод Ссылка на другое место в документации
@param Метод Входной параметр метода
@return Метод Описание возвращаемого значения
@exception имя_класса описание Метод Описание исключения, которое может быть послано из метода
@throws имя_класса описание Метод Описание исключения, которое может быть послано из метода
@deprecated Класс, интерфейс, поле, метод Описание устаревших блоков кода
Класс, интерфейс, поле, метод Ссылка
Статичное поле Описание значения переменной

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

Документирование класса, метода или переменной начинается с комбинации символов /** , после которого следует тело комментариев; заканчивается комбинацией символов */.

В тело комментариев можно вставлять различные дескрипторы. Каждый дескриптор, начинающийся с символа ‘@’ должен стоять первым в строке. Несколько дескрипторов одного и того же типа необходимо группировать вместе. Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.

/** * Класс продукции со свойствами maker и price. * @autor Киса Воробьянинов * @version 2.1 */ class Product < /** Поле производитель */ private String maker; /** Поле цена */ public double price; /** * Конструктор - создание нового объекта * @see Product#Product(String, double) */ Product() < setMaker(""); price=0; >/** * Конструктор - создание нового объекта с определенными значениями * @param maker - производитель * @param price - цена * @see Product#Product() */ Product(String maker,double price) < this.setMaker(maker); this.price=price; >/** * Функция получения значения поля * @return возвращает название производителя */ public String getMaker() < return maker; >/** * Процедура определения производителя * @param maker - производитель */ public void setMaker(String maker) < this.maker = maker; >>

Для документирования кода можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и после символа «#» его метод или поле.

Среда разработки IDE, как правило, помогает программисту «подсветкой» встроенной документации. На следующих рисунках приведены скриншоты всплывающих окон IDE Eclipse.

Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы, для которого генерируется НТМL файл. Документация для каждого класса содержится в отдельном НТМL файле. Кроме этого, создается дерево индексов и иерархии. Могут быть сгенерированы и другие НТМL файлы.

Сценарии ant и javadoc

Для создания документации можно использовать ant.

Пример сценария (задания) ant для формирования документации к приложению MyProject :

           " />       

Подробная информация формирования документации представлена на странице Javadoc/Javadoc2

Источник

Читайте также:  File downloader for java
Оцените статью