Маркировка «пример использования» в документации кода

Question

Какова лучшая практика размещения примера использования в документации кода? Есть ли стандартизированный способ? С @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) {

}

Спасибо

Answer 1

Doxygen имеет команду @ example , и существует множество опций для настройки примеров исходных путей.

Я думаю, что есть общий набор команд между Doxygen и другими инструментами документирования, но их недостаточно для хорошего документирования. Вы должны конкретизировать, чтобы получить лучшее от конкретного инструмента. Мне нравится Doxygen, так как он с открытым исходным кодом и легко настраивается. Но это только мое мнение об этом.

Возможно, вы можете настроить doxygen с псевдонимами @ xrefitem , чтобы разрешить анализ комментариев к документации, определенных другими инструментами документации.