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

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

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

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

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

Требования к документации Поддерживать документацию в актуальном состоянии /** * Произвести парсинг истории операций над невстроенной БД. * * * @throws XMLConfigurationParsingException */ public void parseHistoryNotEmbeddedDB() throws XMLConfigurationParsingException { return ; /* * InputStream is = * Thread.currentThread().GetContextClassLoader(). getResourceAsStream("ru/magnetosoft/magnet/em/cfg/db-configuration-not-embedded.xml"); * String configXml = readStringFromStream(is); * XmlConfigurationParserImpl parser = new * XmlConfigurationParserImpl(configXml); IEmConfiguration res = * parser.parse(); assertNotNull(res); * assertFalse(res.getOperationHistoryStorageConfiguration().isEmbeddedStorage()); * assertEquals("HSQLDB", * 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'и: Обзор Это просто текст обрамлённый особыми комментариями. Они могут описывать классы, методы и переменные класса. Например: /** Текст **/ Он может включать в себя HTML тэги и специальные javadoc тэги, которые позволяют включать дополнительную информацию и ссылки. /** Вставка объектов в очередь. Вставка объектов в конец очереди, но только если нет таких же экземпляров. @since 0.2 @author Malyshkin Fedor ( [email_address] ) **/

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

JavaDoc'и: Тэги @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

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

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

JavaDoc'и: Примеры /** * Представитель модуля EntityManger на клиентской стороне. * * * Данный класс представляет средства доступ к возможностям модуля * EntityManager, минуя прямые вызовы веб-сервисов. * * * Он самостоятельно преобразовывает ваши Java Bean'ы в XML и производит * обратную операцию, при получении ответа от модуля. * * * Для получения экземпляра данного класса предназначены статические методы * {@link #getInstance(InputStream)} и {@link #getInstance(String)} * * * @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 {

Maven 2 & 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>

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>

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>

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

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

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

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

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

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

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

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

More Related Content

What's hot

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

More from Fedor Malyshkin

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