JavaDoc Sync Plugin 8 в IDEA

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

Современные среды разработки позволяют, отчасти, облегчить труд разработчику, и предлагают средства для генерирования javadoc-комментариев.

В среде разработки IntelliJ IDEA, при создании нового класса, автоматически добавляются стандартные комментарии, содержащие информацию об имени автора, дате и времени создания класса. Для полей и методов комментарии приходится писать самостоятельно.

К счастью, для IDEA есть полезный плагин JavaDoc Sync Plugin 8, который позволяет генерировать javadoc'и для полей, методов и классов.

Стоит сказать несколько слов о возможностях плагина.

JavaDoc Sync Plugin позволяет синхронизировать javadoc'и между определениями интерфейса и его реализацией, между методами суперкласса и переопределениями методов в подклассе. Когда javadoc'и методов в подклассе отличаются от тех, что определены в суперклассе, плагин подсвечивает методы подкласса.

JavaDoc Sync Plugin генерирует javadoc по шаблону, который можно изменять.
Если в классе отсутствует javadoc хотя бы для одного метода, плагин подсвечивает определение класса. Также подсвечиваются поля и методы для которых не определены javadoc.

Для установки плагина, нам нужно:

• зайти в настройки IDEA (File -> Settings);
• перейти на страницу Plugins;
• выбрать в списке доступных плагинов (вкладка Available) JavaDoc Sync Plugin 8;
• нажать на кнопку Download And install. 

IDEA спросит нас, хотим ли мы скачать и установить плагин, на что мы положительно отвечаем.

Note: В правой части страницы Plugins можно посмотреть описание каждого выбранного из списка плагина.

После проделанных действий IDEA предлагает перезапустить ее, что мы и делаем.

После перезапуска, нам нужно активировать наш плагин.

Для этого следует зайти в настройках среды разработки на страницу Inspections и поставить галочку напротив JavaDoc issues.

Теперь можно пользоваться плагином.

Для того, чтобы сгенерировать комментарий, например для класса, ставим курсор на его имя, нажимаем клавиши Alt + Enter (в Mac OS X клавиши Option + Enter) и в появившемся контекстном меню, выбираем Generate JavaDoc based on class.

Для методов и полей поступаем аналогичным образом.

Для случаев, когда мы хотим сгенерировать комментарий к методу подкласса или методу класса, реализующего интерфейс, плагин позволяет нам указать в javadoc-комментарии ссылку на javadoc метода суперкласса или интерфейса.

Для изменения шаблона генерирования javadoc необходимо зайти в настройки IDEA на страницу JavaDoc Sync Settings и отредактировать шаблон нужным образом.

Надеюсь, этот пост был Вам полезен, а плагин JavaDoc Sync Plugin 8 поможет Вам  в написании комментариев и сэкономит Ваше драгоценное время =)