2 апр. 2015 г.

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

Здесь коротенько рассмотрим работу с комментариями документации на примере программ AdvancedHello.java и моего пакета pro.java.util содержащего класс Print.java.

Чтобы не описывать все тэги javadoc я просто дам линки на ресурсы где об этом можно почитать, хотя вы можете это нагуглить и сами. Тут я приведу только примеры использования. И так Print.java в студию!

JD0001

Javadoc комментарии вставляются перед классом, методом или переменной. И соответственно документируют эти элементы при помощи простого описания, различных javadoc тэгов (например @param, @version и т.п.), а так же обычных html тэгов.

В приведенном примере использованы html тэги <br> для перехода на новую строку.

Следует так же отметить, что программа генерации комментариев обрабатывает только документирующие комментарии для классов и членов классов с уровнем доступа public и protected по умолчанию.

Это логично потому, что только к ним есть доступ извне и они могут интересовать программиста использующего вашу библиотеку. К private методам и полям он доступа не имеет. Хотя все же эти поля можно включить в документацию используя флаг –private в команде javadoc. Хотя зачем это может быть нужно не особо понятно.

Результатом работы программы javadoc является html файл в том же формате что и вся остальная документация для Java.

Сразу приведу ссылки на документацию по javadoc на сайте Oracle. А так же ссылку на ту же документацию переведенную машинным переводом на русский язык. Хоть это и смешно, но может кому-то  тоже сгодится.

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

Eclipse позволяет сразу же видеть как будут отображаться ваши javadoc комментарии. Для этого достаточно поместить курсор на javadoc комментарий и перейти на вкладку @Javadoc в Eclipse.

JD0002

И после того, как мы правильно подключим комментарии к нашему проекту мы можем наблюдать в нем уже вот такое при наведении курсора на наш класс Print или его методы print, println printf:

JD0003

JD0004

И так существует два основных метода подключения документации к проекту:

  • включение исходных текстов в jar файл
  • генерация документации при помощи javadoc и подключение их к проекту

Включение исходных файлов в jar это самый простой способ, но не самый правильный. Так как чаще всего я думаю вы не захотите включать свои исходники в jar файл.

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

И так начнем с первого способа. Одновременно с ним мы так же узнаем как подключать свои или сторонние библиотеки java к своему проекту в Eclipse.

И так используем первый способ. Генерируем jar файл с библиотекой и включаем в него исходные тексты. Правый клик по проекту и затем выбираем Export.

JD0005

Далее

JD0006

Далее

JD0007

Далее

JD0008

Далее

JD0009

Далее, чтобы показать как подключать данную библиотеку, я ее отключил от проекта AdvancedHello и поэтому на нем светятся красные крестики, так как проект не видит библиотеку.

Подключение библиотеки Java к проекту в Eclipse.

И так, правый клик по проекту AdvancedHello, к которому мы подключаем библиотеку

JD0010

JD0011

Выбираем подключаемую библиотеку. Красный восклицательный знак стоит потому, что это файл у меня стоит под контролем версий и еще пока не закоммичен. У вас скорей всего восклицательного знака на иконке файла не будет. И вообще забейте пока на это.

JD0012

Далее видим нашу библиотеку как добавленную и жмем ОК.

JD0013

Красный крестик у проекта исчез, так как библиотека найдена. Ну и собственно видим в работе наши javadoc комментарии.

JD0004

Теперь посмотрим что же внутри сгенерированного файла ProJava.jar. Jar это на самом деле просто zip архив.

JD0014

И видим что внутри jar архива лежит как скомпилированный класс Print.class так и его исходники Print.java, которые мы можем посмотреть:

JD0015

В большинстве случаев такой вариант не очень хорошая идея. Так как это увеличивает размер jar файла, а так же раскрывает ваши исходные тексты, которыми вы возможно не захотите делится.

Поэтому сейчас рассмотрим другой вариант: генерацию документации как html файлов их архивирование и подключение к проекту. Так же для чистоты эксперимента, нам надо будет перекомпилировать нашу библиотеку ProJava.jar чтобы исключить из нее исходные тексты.

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

JD0016

Далее все так же как было.

Теперь проверяем, что javadoc комментарии не доступны в проекта AdvancedHello

JD0017

Ну и быстренько посмотрим внутрь архива ProJava.jar

JD0018

Теперь там только один наш бинарный файл Print.class, собственно поэтому javadoc комментарии и недоступны в проекте AdvancedHello.java.

Теперь сгенерируем документацию при помощи утилиты javadoc. Для этого я создал специальную папку doc на том же уровне что и src и bin. Дабы был порядок.

JD0019

Теперь собственно идем в подпапку где лежит наш исходник Print.java и генерируем документацию командой:

javadoc -d C:\Git\StudyingJava\ProJava\doc Print.java

JD0020

Собственно в этой команде мы указали куда сложить документацию (C:\Git\StudyingJava\ProJava\doc) и из какого файла ее сгенерировать (Print.java). И вот что у нас получилось в подкаталоге doc:

JD0021

Теперь выделяем все эти файлы и папочку pro и создаем zip архив из всего этого хозяйства, удалив после архивации все эти файлики.

JD0022

Теперь подкаталог doc выглядит вот так:

JD0023

Все! Далее подключаем эту документацию к нашему проекту AdvancedHello.java. Для этого правый клик по проекту и погнали…

JD0024

Видим это и раскрываем узел ProJava.jar

JD0025

Указываем путь к нашему архиву.

JD0026

И можем нажать кнопку Validate… чтобы убедиться что все хорошо.

JD0027

Жмем два раза ОК и должны увидеть такое

JD0028

То есть мы подключили javadoc к нашей импортированной библиотеке. Опять жмем ОК и проверяем работу подключенных javadoc комментариев.

JD0029

Все работает. Правда выглядит чуток по другому.

Мы так же можем посмотреть эту документацию в html формате. Можно извлечь все обратно из архива в какой-нибудь подкаталог или же посмотреть прямо из архива кликнув на файле index.html.

Вот так все красивенько выглядит в бразузере

JD0030

Все на этом по javadoc все Smile если надо больше гугль в помощь!

Этот пример можно будет найти в коммите 31e057b. В следующих коммитах я удалю эти javadoc комментарии, так как они мне не нужны. И кроме того есть такое высказывание, что код должен объяснять сам себя, то есть комментариев должно быть по минимуму. Но это вообще отдельная тема.

Вообще комментировать текст полезно, так как если приходится возвращаться к коду через долгий промежуток времени, то комменты выручают. Но в случае этой небольшой библиотеки комментарии не нужны, так как код и так простой и понятный.

А если они вам нужны то смотрите в упомянутом коммите или же в коммите перед ним.

Как пользоваться Git читайте тут. Если это пока сложно, то забейте на это и смотрите исходники прямо через веб.

Комментариев нет:

Отправить комментарий