Нижний колонтитул отчета не экспортируется в Excel

Сгенерированная документация почти всегда совершенно бесполезна.

Или, как следствие: Вашему API требуется отдельный набор документации для сопровождающих и пользователей.

На самом деле есть два класса людей, которым нужно понимать ваш API: сопровождающие, которые должны понимать мелочи вашей реализации, чтобы быть эффективными в своей работе, и пользователи, которым нужен общий обзор, примеры и подробные сведения о влиянии каждого метода, к которому они имеют доступ.

Я никогда не встречал сгенерированную документацию, которая преуспела ни в одной области. Как правило, когда программисты пишут комментарии к инструментам для извлечения и создания документации, они стремятся к чему-то посередине - просто достаточно деталей реализации, чтобы утомлять и запутывать пользователей, но недостаточно, чтобы значительно помочь сопровождающим, и недостаточно общего обзора, чтобы реальная помощь пользователям.

Как сопровождающий, я бы всегда предпочел бы иметь чистые, четкие комментарии, не смешанные с какой-либо странной разметкой, необходимой вашему инструменту auto-doc, которая скажет мне, почему вы написали этот странный оператор switch так, как вы это делали или какую ошибку исправляет эта кажущаяся избыточной проверка параметров, или что еще мне нужно знать, чтобы на самом деле сохранить код чистым и без ошибок, пока я работаю над ним. Я хочу, чтобы эта информация была прямо в коде рядом с кодом, о котором идет речь, поэтому мне не нужно выслеживать ваш сайт, чтобы найти его в состоянии, пригодном для чтения.

Как пользователь, я всегда предпочел бы иметь тщательный, хорошо организованный документ (набор веб-страниц был бы идеальным, но я бы тоже согласился на хорошо структурированный текстовый файл). ) рассказывая, как устроен ваш API, какие методы делают и как я могу достичь того, что я хочу использовать для вашего API. Я не хочу видеть внутри себя, какие классы вы написали, чтобы позволить мне выполнять работу, или файлы, в которых они находятся. И я, конечно же, не хочу загружать ваш источник, чтобы точно понять, что происходит за кулисами. Если бы ваша документация была достаточно хорошей, мне бы не пришлось.

Так или иначе, я так вижу.