Документирование исходных текстов (javadoc)

50 %
50 %
Information about Документирование исходных текстов (javadoc)

Published on June 25, 2008

Author: fedor.malyshkin

Source: slideshare.net

Description

Документирование исходных текстов (javadoc)

Малышкин Фёдор 11 октября 2007 Документирование исходных текстов

Малышкин Фёдор

11 октября 2007

Основание для ведения документации Требования к документации JavaDoc'и Обзор Тэги Примеры Maven2 & JavaDoc'и NetBeans & JavaDoc'и Ресурсы для JavaDoc'ов в сети фирмы Дополнительная документация TODO Оглавление

Основание для ведения документации

Требования к документации

JavaDoc'и

Обзор

Тэги

Примеры

Maven2 & JavaDoc'и

NetBeans & JavaDoc'и

Ресурсы для JavaDoc'ов в сети фирмы

Дополнительная документация

TODO

Основание для ведения документации Возобновление работы над проектом после продолжительного перерыва Переход проекта от одного человека (группы) к другому человеку (группе) Опубликование проекта для Open Source сообщества Совместная работа большой группы людей над одним проектом

Возобновление работы над проектом после продолжительного перерыва

Переход проекта от одного человека (группы) к другому человеку (группе)

Опубликование проекта для Open Source сообщества

Совместная работа большой группы людей над одним проектом

Основание для ведения документации Требования к документации JavaDoc'и Обзор Тэги Примеры Maven2 & JavaDoc'и NetBeans & JavaDoc'и Ресурсы для JavaDoc'ов в сети фирмы Дополнительная документация TODO Оглавление

Основание для ведения документации

Требования к документации

JavaDoc'и

Обзор

Тэги

Примеры

Maven2 & JavaDoc'и

NetBeans & JavaDoc'и

Ресурсы для JavaDoc'ов в сети фирмы

Дополнительная документация

TODO

Требования к документации Не документировать очевидные вещи (setter'ы и getter'ы, циклы по массивам и листам, вывод логов и прочее) /** * Проверка: редактируема ли даннная ячейка. * * <p>В случае если данная ячаейка редактируема - возвращается true</p> * * <p>В случае если данная ячаейка не редактируема - возвращается false</p> * * @param column номер колонки для проверки * @return результат проверки **/ public boolean isCellEditable(int column) { return column % 2 == 0 ? true : false; }

Не документировать очевидные вещи (setter'ы и getter'ы, циклы по массивам и листам, вывод логов и прочее)

Требования к документации Поддерживать документацию в актуальном состоянии /** * Произвести парсинг истории операций над невстроенной БД. * * * @throws XMLConfigurationParsingException */ public void parseHistoryNotEmbeddedDB() throws XMLConfigurationParsingException { return ; /* * InputStream is = * Thread.currentThread().GetContextClassLoader(). getResourceAsStream(&quot;ru/magnetosoft/magnet/em/cfg/db-configuration-not-embedded.xml&quot;); * String configXml = readStringFromStream(is); * XmlConfigurationParserImpl parser = new * XmlConfigurationParserImpl(configXml); IEmConfiguration res = * parser.parse(); assertNotNull(res); * assertFalse(res.getOperationHistoryStorageConfiguration().isEmbeddedStorage()); * assertEquals(&quot;HSQLDB&quot;, * res.getOperationHistoryStorageConfiguration().getStorageDBType()); */ }

Поддерживать документацию в актуальном состоянии

Требования к документации Описывать входящие параметры, если нужно /** * Создание нового экземпляра ядра. * * * @param contextName * @param objectRelationManager * @param xmlObjectPersister * @param ohm * @param snm * @param initializationLatch * @return */ public static EmEngine newInstance(String contextName, IXmlObjectRelationManager objectRelationManager, IXmlObjectPersister xmlObjectPersister, OperationHistoryManager ohm, ISearchNotificationManager snm, CountDownLatch initializationLatch) { ... ... }

Описывать входящие параметры, если нужно

Основание для ведения документации Требования к документации JavaDoc'и Обзор Тэги Примеры Maven2 & JavaDoc'и NetBeans & JavaDoc'и Ресурсы для JavaDoc'ов в сети фирмы Дополнительная документация TODO Оглавление

Основание для ведения документации

Требования к документации

JavaDoc'и

Обзор

Тэги

Примеры

Maven2 & JavaDoc'и

NetBeans & JavaDoc'и

Ресурсы для JavaDoc'ов в сети фирмы

Дополнительная документация

TODO

JavaDoc'и: Обзор Это просто текст обрамлённый особыми комментариями. Они могут описывать классы, методы и переменные класса. Например: /** Текст **/ Он может включать в себя HTML тэги и специальные javadoc тэги, которые позволяют включать дополнительную информацию и ссылки. /** Вставка объектов в очередь. <p>Вставка объектов в конец очереди, но только если нет таких же экземпляров<p>. @since 0.2 @author Malyshkin Fedor ( [email_address] ) **/

Это просто текст обрамлённый особыми комментариями. Они могут описывать классы, методы и переменные класса.

Например:

/**

Текст

**/

Он может включать в себя HTML тэги и специальные javadoc тэги, которые позволяют включать дополнительную информацию и ссылки.

/**

Вставка объектов в очередь.

<p>Вставка объектов в конец очереди, но только если нет таких же экземпляров<p>.

@since 0.2

@author Malyshkin Fedor ( [email_address] ) **/

JavaDoc'и: Обзор Структура каждого javadoc коментария такова: Первая строчка, которая попадает в краткое описание класса (отделяется точкой и пустой строкой). Основной текст, который вместе с HTML тэгами кописруется в основную документацию. Входящие параметры (если есть) Выбрасываемые исключения (если есть) Возвращаемое значение (если есть) Служебные Javadoc тэги

Структура каждого javadoc коментария такова:

Первая строчка, которая попадает в краткое описание класса (отделяется точкой и пустой строкой).

Основной текст, который вместе с HTML тэгами кописруется в основную документацию.

Входящие параметры (если есть)

Выбрасываемые исключения (если есть)

Возвращаемое значение (если есть)

Служебные Javadoc тэги

JavaDoc'и: Обзор

Основание для ведения документации Требования к документации JavaDoc'и Обзор Тэги Примеры Maven2 & JavaDoc'и NetBeans & JavaDoc'и Ресурсы для JavaDoc'ов в сети фирмы Дополнительная документация TODO Оглавление

Основание для ведения документации

Требования к документации

JavaDoc'и

Обзор

Тэги

Примеры

Maven2 & JavaDoc'и

NetBeans & JavaDoc'и

Ресурсы для JavaDoc'ов в сети фирмы

Дополнительная документация

TODO

JavaDoc'и: Тэги @see – ссылка на дополнительные классы или пакеты (все ссылки оформляются в виде: «packageName.className#methodName(argument1, argument2,...)», где пакет указывается лишь в случае если ссылаемся на класс в другом пакете, а аргументы (т.е. типы аргументов) – лишь в случае если есть метод с тем же именем). Т.е. можно написать так: @see java.io.RandomAccessFile#RandomAccessFile(File, String) а можно и так: @see CreationManager

@see – ссылка на дополнительные классы или пакеты (все ссылки оформляются в виде: «packageName.className#methodName(argument1, argument2,...)», где пакет указывается лишь в случае если ссылаемся на класс в другом пакете, а аргументы (т.е. типы аргументов) – лишь в случае если есть метод с тем же именем). Т.е. можно написать так:

@see java.io.RandomAccessFile#RandomAccessFile(File, String)

а можно и так:

@see CreationManager

JavaDoc'и: Тэги @author – автор кода @author Mary Wollstonecraft @author Jack Kent, Peggy Parish, Crockett Johnson @version – версия продукта (если нужно) @version 493.0.1beta @since – с какой версии появлось в продукте @since 493.0.1beta @param – (с именем параметра) описание входящего параметра @param column номер колонки для проверки @param row номер ряда для проверки @return – описание возвращаемого значения @throws – (с типом исключения) описание исключения @throws XmlMagnetException @throws EntityManagerException

@author – автор кода

@author Mary Wollstonecraft

@author Jack Kent, Peggy Parish, Crockett Johnson

@version – версия продукта (если нужно)

@version 493.0.1beta

@since – с какой версии появлось в продукте

@since 493.0.1beta

@param – (с именем параметра) описание входящего параметра

@param column номер колонки для проверки

@param row номер ряда для проверки

@return – описание возвращаемого значения

@throws – (с типом исключения) описание исключения

@throws XmlMagnetException

@throws EntityManagerException

JavaDoc'и: Тэги @link – позволяет сделать ссылку на другой класс, метод или пакет. Обратите внимание на фигурные скобки. {@link #getInstance(InputStream)} {@link #getInstance(String)} {@link java.io.InputStream(String)}

@link – позволяет сделать ссылку на другой класс, метод или пакет. Обратите внимание на фигурные скобки.

{@link #getInstance(InputStream)}

{@link #getInstance(String)}

{@link java.io.InputStream(String)}

JavaDoc'и: Обзор Есть возможность применять комментарии для пакетов. Для этого необходимо поместить файл package.html в пакет с исходными текстами. Данный файл должен быть обычным HTML файлом с тэгом <BODY>. Первая строчка файла до точки идёт в краткое описание пакета, а полное описание идёт вниз – под список всех классов и исключений. Этот функционал позволяет описать что-то, что невозможно описать с помощью конкретных классов.

Есть возможность применять комментарии для пакетов. Для этого необходимо поместить файл package.html в пакет с исходными текстами.

Данный файл должен быть обычным HTML файлом с тэгом <BODY>.

Первая строчка файла до точки идёт в краткое описание пакета, а полное описание идёт вниз – под список всех классов и исключений.

Этот функционал позволяет описать что-то, что невозможно описать с помощью конкретных классов.

Основание для ведения документации Требования к документации JavaDoc'и Обзор Тэги Примеры Maven2 & JavaDoc'и NetBeans & JavaDoc'и Ресурсы для JavaDoc'ов в сети фирмы Дополнительная документация TODO Оглавление

Основание для ведения документации

Требования к документации

JavaDoc'и

Обзор

Тэги

Примеры

Maven2 & JavaDoc'и

NetBeans & JavaDoc'и

Ресурсы для JavaDoc'ов в сети фирмы

Дополнительная документация

TODO

JavaDoc'и: Примеры /** * Представитель модуля EntityManger на клиентской стороне. * * <p> * Данный класс представляет средства доступ к возможностям модуля * EntityManager, минуя прямые вызовы веб-сервисов. * </p> * <p> * Он самостоятельно преобразовывает ваши Java Bean'ы в XML и производит * обратную операцию, при получении ответа от модуля. * </p> * <p> * Для получения экземпляра данного класса предназначены статические методы * {@link #getInstance(InputStream)} и {@link #getInstance(String)} * </p> * * @created 09.11.2006 * @version $Revision 738 $ * @author MalyshkinF * @since 0.2.2 */ public class EntityManagerInvoker {

/**

* Представитель модуля EntityManger на клиентской стороне.

*

* <p>

* Данный класс представляет средства доступ к возможностям модуля

* EntityManager, минуя прямые вызовы веб-сервисов.

* </p>

* <p>

* Он самостоятельно преобразовывает ваши Java Bean'ы в XML и производит

* обратную операцию, при получении ответа от модуля.

* </p>

* <p>

* Для получения экземпляра данного класса предназначены статические методы

* {@link #getInstance(InputStream)} и {@link #getInstance(String)}

* </p>

*

* @created 09.11.2006

* @version $Revision 738 $

* @author MalyshkinF

* @since 0.2.2

*/

public class EntityManagerInvoker {

JavaDoc'и: Примеры /** * Произвести запись нового объекта. * * Произвести запись нового объекта. Тип для сохранения может быть * подклассом List (для реализации возможности работы с несколькими * объектами) или единичным объектом. В случае если произошла какая-либо * ошибка - выбрасывается исключение. В данном случае с базой не происходит * никаких изменений и ни один объект не был затрагивается предполагаемой * операцией. Конкретный тип ошибки можно определить проверкой конкретного * возвращённого исключения. * * @param object * сохраняемый объект/объекты. * @return сохраненный объект/объекты * @throws XmlMagnetException ошибка в процессе парсинга XML * @throws EntityManagerException ошибка связанная с другой работой клиента */ public Object insert(Object object) throws XmlMagnetException, EntityManagerException {

/**

* Произвести запись нового объекта.

*

* Произвести запись нового объекта. Тип для сохранения может быть

* подклассом List (для реализации возможности работы с несколькими

* объектами) или единичным объектом. В случае если произошла какая-либо

* ошибка - выбрасывается исключение. В данном случае с базой не происходит

* никаких изменений и ни один объект не был затрагивается предполагаемой

* операцией. Конкретный тип ошибки можно определить проверкой конкретного

* возвращённого исключения.

*

* @param object

* сохраняемый объект/объекты.

* @return сохраненный объект/объекты

* @throws XmlMagnetException ошибка в процессе парсинга XML

* @throws EntityManagerException ошибка связанная с другой работой клиента

*/

public Object insert(Object object) throws XmlMagnetException, EntityManagerException {

Основание для ведения документации Требования к документации JavaDoc'и Обзор Тэги Примеры Maven2 & JavaDoc'и NetBeans & JavaDoc'и Ресурсы для JavaDoc'ов в сети фирмы Дополнительная документация TODO Оглавление

Основание для ведения документации

Требования к документации

JavaDoc'и

Обзор

Тэги

Примеры

Maven2 & JavaDoc'и

NetBeans & JavaDoc'и

Ресурсы для JavaDoc'ов в сети фирмы

Дополнительная документация

TODO

Maven 2 & JavaDoc'и Поддержка генерации javadoc Настраиваемые в pom.xml параметры для генерации javadoc Автоматическая генерация и закачка в репозитарий javadoc'ов при создании релиза ...

Поддержка генерации javadoc

Настраиваемые в pom.xml параметры для генерации javadoc

Автоматическая генерация и закачка в репозитарий javadoc'ов при создании релиза

...

Maven 2 & JavaDoc'и Для генерации javadoc'ов в существует plugin javadoc: $malyshkiknf> mvn javadoc:javadoc Для автоматической генерации при каждой сборке необходимо добавить в корневой тэг такой XML: <reporting> ... <plugins> ... <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> </plugin> ... </plugins> ... </reporting>

Для генерации javadoc'ов в существует plugin javadoc:

$malyshkiknf> mvn javadoc:javadoc

Для автоматической генерации при каждой сборке необходимо добавить в корневой тэг такой XML:

<reporting>

...

<plugins>

...

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-javadoc-plugin</artifactId>

</plugin>

...

</plugins>

...

</reporting>

Maven 2 & JavaDoc'и Возможно объединить javadoc'и от нескольких дочерних проектов. Для этого нужно откорректировать корневой pom.xml. <reporting> ... <plugins> ... <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <configuration> ... <aggregate>true</aggregate> ... </configuration> </plugin> ... </plugins> ... </reporting>

Возможно объединить javadoc'и от нескольких дочерних проектов. Для этого нужно откорректировать корневой pom.xml.

<reporting>

...

<plugins>

...

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-javadoc-plugin</artifactId>

<configuration>

...

<aggregate>true</aggregate>

...

</configuration>

</plugin>

...

</plugins>

...

</reporting>

Maven 2 & JavaDoc'и Можно группировать пакеты по сходному назначению или использованию в группы. <groups> <group> <title>Clients Part</title> <packages>ru.magnetosoft.magnet.em.client: ru.magnetosoft.magnet.em.client.cfg</packages> </group> <group> <title>Common Part</title> <packages>ru.magnetosoft.magnet.em.annotations: ru.magnetosoft.magnet.em.metadata: ru.magnetosoft.magnet.em.xml: ru.magnetosoft.magnet.em.xml.parts: ru.magnetosoft.magnet.em.xml.parts.v2: </packages> </group> </groups>

Можно группировать пакеты по сходному назначению или использованию в группы.

<groups>

<group>

<title>Clients Part</title> <packages>ru.magnetosoft.magnet.em.client:

ru.magnetosoft.magnet.em.client.cfg</packages>

</group>

<group>

<title>Common Part</title>

<packages>ru.magnetosoft.magnet.em.annotations:

ru.magnetosoft.magnet.em.metadata:

ru.magnetosoft.magnet.em.xml:

ru.magnetosoft.magnet.em.xml.parts:

ru.magnetosoft.magnet.em.xml.parts.v2:

</packages>

</group>

</groups>

Основание для ведения документации Требования к документации JavaDoc'и Обзор Тэги Примеры Maven2 & JavaDoc'и NetBeans & JavaDoc'и Ресурсы для JavaDoc'ов в сети фирмы Дополнительная документация TODO Оглавление

Основание для ведения документации

Требования к документации

JavaDoc'и

Обзор

Тэги

Примеры

Maven2 & JavaDoc'и

NetBeans & JavaDoc'и

Ресурсы для JavaDoc'ов в сети фирмы

Дополнительная документация

TODO

NetBeans & JavaDoc'и Просмотр JavaDoc'ов в отдельном окне и в контекстом Помощь в генерации JavaDoc'ов Возможность подключения JavaDoc'ов к используемым библиотекам P.S.: Примеры будут показываться на NetBeans 6

Просмотр JavaDoc'ов в отдельном окне и в контекстом

Помощь в генерации JavaDoc'ов

Возможность подключения JavaDoc'ов к используемым библиотекам

P.S.: Примеры будут показываться на NetBeans 6

NetBeans & JavaDoc'и Для активации поддержки JavaDoc'ов необходимо кое-что включить в NetBeans

Для активации поддержки JavaDoc'ов необходимо кое-что включить в NetBeans

NetBeans & JavaDoc'и Отдельное окно с информацией о JavaDoc

Отдельное окно с информацией о JavaDoc

NetBeans & JavaDoc'и Контекстно меню. Как обычно при нажатии Ctrl+Space...

Контекстно меню. Как обычно при нажатии Ctrl+Space...

NetBeans & JavaDoc'и Помощь в генераци JavaDoc. Наводим курсор на определение класса и ждём... Нажимаем на лампочку .... Вуаля...

Помощь в генераци JavaDoc.

Наводим курсор на определение класса и ждём...

Нажимаем на лампочку ....

Основание для ведения документации Требования к документации JavaDoc'и Обзор Тэги Примеры Maven2 & JavaDoc'и NetBeans & JavaDoc'и Ресурсы для JavaDoc'ов в сети фирмы Дополнительная документация TODO Оглавление

Основание для ведения документации

Требования к документации

JavaDoc'и

Обзор

Тэги

Примеры

Maven2 & JavaDoc'и

NetBeans & JavaDoc'и

Ресурсы для JavaDoc'ов в сети фирмы

Дополнительная документация

TODO

Ресурсы для JavaDoc'ов HTTP Server на mg-sv01 и шара g-sv01javadocs

HTTP Server на mg-sv01 и шара g-sv01javadocs

Основание для ведения документации Требования к документации JavaDoc'и Обзор Тэги Примеры Maven2 & JavaDoc'и NetBeans & JavaDoc'и Ресурсы для JavaDoc'ов в сети фирмы Дополнительная документация TODO Оглавление

Основание для ведения документации

Требования к документации

JavaDoc'и

Обзор

Тэги

Примеры

Maven2 & JavaDoc'и

NetBeans & JavaDoc'и

Ресурсы для JavaDoc'ов в сети фирмы

Дополнительная документация

TODO

TODO Подобно многим другим средам разработки NetBeans позволяет оставлять особые коментарии в исходных текстах, которые могут быть собраны и выведены на экран. Это могут быть личные заметки о необходимости дополнительной проверки кода, переработки в дальнейшем и прочие записи.

Подобно многим другим средам разработки NetBeans позволяет оставлять особые коментарии в исходных текстах, которые могут быть собраны и выведены на экран. Это могут быть личные заметки о необходимости дополнительной проверки кода, переработки в дальнейшем и прочие записи.

Add a comment

Related presentations

Related pages

Java Doc - Анализ сайта, проверка ...

Документирование исходных текстов (javadoc) ... Maven2 & JavaDoc'и. 7. Javadoc - Wikipedia, the free encyclopedia
Read more

Codigo javadoc - Documents - Discover, share, present ...

Документирование исходных текстов (javadoc) Документирование исходных текстов ...
Read more

009. Javadoc - workpalace2012

Документация в формате javadoc, созданная на основе исходных текстов версии 0.5.1 ...
Read more

Расположение документации ...

... Документирование исходных текстов; ... By default a JavaDoc style documentation block behaves the same way as a Qt style ...
Read more

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

включение исходных текстов в ... Включение исходных файлов в jar это самый ... javadoc -d C: Git ...
Read more

Шаг 3: Документирование ...

Шаг 3: Документирование исходных текстов Несмотря на то, что документирование ...
Read more

Java Classes

Java Classes Позиции сайта в Google, ... Документирование исходных текстов (javadoc)
Read more

Применение системы ...

Применение системы документирования исходных текстов ... документирование ...
Read more