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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Далее

Далее

Далее

Далее

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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