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

Question

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

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

Я экспериментировал с 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 псевдонимов, чтобы разрешить комментарии к документации для синтаксического анализа, определенные другими инструментами документации.