Разработчики довольно часто добавляют тэги Javadoc и краткие комментарии, когда они создают код Java. Фактически, если они не добавляют некоторые аннотации, среда IDE обычно выдает предупреждение об ошибке.
Однако комментарии, которые добавляют разработчики, могут быть плохими, неполными или непонятными. Работа технического писателя с Javadoc часто заключается в редактировании уже существующего контента, обеспечивая большую ясность, структуру, вставляя правильные теги и многое другое.
На что обращать внимание при редактировании Javadoc
При редактировании Javadoc обращаем внимание на:
- отсутствие документации (большая часть Javdoc неполная, нужно искать недостающую документацию);
- последовательный стиль (соответствуют ли существующие тэги соглашениям стиля Java с аннотациями )
- ясность (некоторые описания неразборчивы из-за проклятия знаний, и без хорошего понимания Java может быть трудно разобраться в них).
Сделаем несколько изменений в классе и методе. Затем заново сгенерируем Javadoc и посмотрим на изменения, как они отображаются на выходе.
Как экспортировать Javadoc можно посмотреть в разделе Практическое занятие: Генерация Javadoc из примера проекта. Каждый раз, экспортируя Javadoc, нужно выбирать какие классы включать.