Отмечание “использования в качестве примера” в документации кода
Какова лучшая практика помещающего использования в качестве примера в документации кода? Существует ли стандартизованный способ? С @usage или @notes? Генераторы документа имеют тенденцию поддерживать это?
Я знаю, что этот вопрос должен зависеть от генератора документации. Однако я пытаюсь получить привычку к использованию стиля комментария для поколения документа перед вхождением в особенности каждого генератора; кажется, что существует больше общих черт, чем различия.
Я экспериментировал с Doxygen и часто использую AS3, JS, PHP, Obj-C, C++.
Например:
/**
* My Function
* @param object id anObject
* @usage a code example here...
*/
function foo(id) {
}
или
/**
* My Function
* @param object id anObject
* @notes a code example here, maybe?
*/
function foo(id) {
}
Спасибо
1 ответ
В Doxygen есть команда @example, и в ней много опций для настройки путей к исходникам примеров.
Я думаю, что есть общий набор команд между Doxygen и другими инструментами документирования, но их слишком мало для хорошего документирования. Вам нужно специализироваться, чтобы получить лучшее от конкретного инструмента. Мне нравится Doxygen, поскольку он с открытым исходным кодом и хорошо настраивается. Но это только мое мнение о нем.
Возможно, вы могли бы настроить doxygen с @xrefitem псевдонимами, чтобы позволить разбирать комментарии к документации, определенные с помощью других инструментов документирования.