​​JavaDoc

JavaDoc — cпециальные комментарии, которые предназначены для документирования Java-кода. С помощью этих комментариев можно описывать классы, интерфейсы, переменные, методы, пакеты. Хороший JavaDoc помогает новым пользователям быстро разобраться с библиотекой, с которой он не знаком.

Лучшие примеры JavaDoc — исходники самой Джавы. В каждом классе подробно описано, что делают и чего не делают методы, при каких условиях они работают, и как они справляются с ошибками. В общем, хорошая документация та, после которой не нужно гуглить туториалы или подходить к человеку, который её написал.