ну так поэтому и удивлён был, что речь то шла об одном единственном авторе

Это с чего бы? Хоть 500 авторов. Каждый документирует СВОИ изменения. Работа в команде без выделенных ролей, угу.

А если глянете в те доки, что считаете хорошими с другого угла, то можно будет заметить, что большая часть текста базируется именно на коде класса.

Мнэ. Кто на ком стоял осталось понять. Так-то было быстранно чтобы код не был похож на описание. А когда к интерфейсу, у которого 100 реализаций, документацию пишут, на какой из 100 реализаций основывают код?

В общем мой диагноз: ты тоже жертва ЕГЭ :) В смысле никогда не видел и никогда не писал сам нормальную документацию к коду,

Конечно же есть классы и методы, у которых их описание будет полностью совпадать с кодом.

Но так же (должно быть очевидно) что есть классы / интерфейсы / методы у которых не с чем совпадать. Потому что они, падлы, абстрактные. И программист описывает для них зачем он это придумал и что он должен делать. А тот, кто их реализует, пишет свой код так, чтобы соответствовало описанию абстрактного.