Я хочу написать Javadoc в сухом виде. Но документ оракула о Javadoc говорит, что напишите то же самое снова в комментарии метода перегрузки. Могу ли я избежать повторения?
Я хочу написать Javadoc в сухом виде. Но документ оракула о Javadoc говорит, что напишите то же самое снова в комментарии метода перегрузки. Могу ли я избежать повторения?
Ответы:
Я размещаю {@inheritDoc}директивы здесь и там в моих комментариях Javadoc при переопределении методов из суперклассов или реализации методов, определенных интерфейсом.
По крайней мере, это хорошо работает для меня, позволяет избежать повторений в исходном коде, и вы все равно можете добавить конкретную информацию к конкретному комментарию Javadoc, если в этом есть необходимость. Я не учитываю тот факт, что сам комментарий Javadoc довольно проблематичен, когда все, что требуется в приличной среде IDE, - это навести курсор мыши на имя связанного идентификатора, чтобы получить визуализированный Javadoc со ссылками и всем остальным.
Смысл документации - осветить будущих пользователей предмета. Это частично для удобства автора, так что с ним или с ней не нужно связываться всякий раз, когда кто-то не может понять, как это работает. В основном, однако, это на благо людей, которые должны использовать или поддерживать вещь.
Как таковой, суть должна быть ясностью, а не удобством для автора. Вы не можете ожидать, что люди будут копаться в документации по API, потому что вы были слишком ленивы, чтобы повторяться. Смиритесь - Javadoc будет повторяться.
Тем не менее, нет никаких причин, если вы умны, вы не можете написать программу, которая будет вставлять комментарии в ваш код на основе маркеров или каких-то других критериев. Это может быть больше проблем, чем оно того стоит. Или нет.