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

Как лучше всего размещать примеры использования в документации по коду? Есть ли стандартный способ? С @usage или @notes? Поддерживают ли генераторы документов это?

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

Я экспериментировал с Doxygen и часто использую AS3, JS, PHP, Obj-C, C++.

Например:

/**
 * My Function
 * @param object id  anObject 
 * @usage a code example here... 
 */
function foo(id) {

}

or 

/**
 * My Function
 * @param object id  anObject 
 * @notes a code example here, maybe?
 */
function foo(id) {

}

Спасибо


documentation javadoc documentation-generation doxygen
person Community    schedule 09.03.2010    source источник

Ответы (1)


arrow_upward
4
arrow_downward

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

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

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

person Community    schedule 09.03.2010
comment
большое спасибо - это привело меня на правильный путь. жаль, что @example не может включать примеры встроенного кода. - person Ross; 10.03.2010