Відповіді:
Я розсипаю {@inheritDoc}директиви тут і там у своїх коментарях Javadoc, коли переосмислюють методи із суперклассів або реалізують визначені інтерфейсом методи.
Принаймні це добре для мене, дозволяє уникнути повторення у вихідному коді, і ви можете додати конкретну інформацію до конкретного коментаря Javadoc, якщо в цьому є потреба. Я не вважаю той факт, що коментар Javadoc сам по собі є досить голим питанням, коли все, що потрібно для пристойного IDE, - навести курсор на відповідне ім'я ідентифікатора, щоб отримати виведений Javadoc з посиланнями та ін.
Суть документації полягає у висвітленні майбутніх користувачів товару. Частково це зручно для автора, так що з ним не потрібно звертатися, коли хтось не може зрозуміти, як ця річ працює. Переважно, однак, це приносить користь людям, яким потрібно використовувати або підтримувати річ.
Таким чином, суть має бути чіткістю, а не зручністю для автора. Ви не можете розраховувати, що люди будуть шукати вгору та вниз за допомогою своєї документації API, тому що ви були дуже ліниві, щоб повторити себе. Висмотри це - Javadoc буде повторюватися.
Це означає, що немає ніякої причини, якщо ви розумні, ви не можете написати програму, яка б вставляла коментарі до вашого коду на основі маркерів чи інших критеріїв. Це може бути більше клопоту, ніж варто. Чи ні.