Давайте перестанем путать комментарии в коде и документацию. Если первое предназначено для объяснения как это вообще работает, то второе ставит перед собой цель описания интерфейса взаимодействия, краткие описания с примерами использования и другие вещи, позволяющие, например, автоматически генерировать документацию