> Комментарии и API - это другое дело.

Нет, не другое. Смотря какую документацию мы имеем в виду и что пишем. Если у тебя библиотека, которой будут пользоваться многие, то очевидно, что нужно документировать API(вместе с примерами).