Как мне поддерживать документацию высокого уровня вместе с документацией, сгенерированной phpdoc? - PullRequest
Новая
       14

Как мне поддерживать документацию высокого уровня вместе с документацией, сгенерированной phpdoc?

4 голосов
/ 20 августа 2009

Для моего первого проекта с открытым исходным кодом ( бесстыдный плагин: mtChart ) в настоящее время у меня есть два разных типа документации:

  • HTML-файлы, сгенерированные Doxygen из phpdoc-комментариев внутри кода
  • Вики-страницы в Google Code (проще говоря: дополнительные текстовые файлы)

Файлы Doxygen действительно великолепны, но я упускаю возможность добавить «высокоуровневую» документацию: учебные пособия, примеры, обзор системы, дорожные карты и т. Д.

Как мне объединить эти два в автоматическом режиме, чтобы я мог автоматически обновлять документацию кода, как и остальные тексты?

(Я готов отойти от Doxygen в случае необходимости.)

1 Ответ

3 голосов
/ 26 августа 2009

Если вы используете стиль phpdoc, вы, очевидно, понимаете, что можете создавать примеры, учебные пособия и т. Д. Прямо внутри него и предоставлять ссылки на внешний контент, например, дорожные карты. Это не идеально, но определенно работает и дает вам последовательную и полезную документацию. Просто используйте форматирование внутри ваших комментариев для удобочитаемого текста и @see для ссылок. Вы также можете рассмотреть возможность использования встроенных тегов, но я не уверен, что вам нужно идти так далеко с самого начала. 

/**
 * @todo Need to move to the main framework
 *
 *        class: RegistrationPeer extends AbstractPeer
 *      package: Registration
 *   subpackage: Peer
 *
 *       method: findByUserId($userId)
 *   visibility: public
 *       static: yes
 *
 *         file: xxx
 *
 *        class: Registration extends AbstractModel
 *      package: Registration
 *   subpackage: Model
 *
 * Sample usage:
 * <code>
 * <?php
 *     $userId = $sessionManager->getRegUid();
 *     $registration = RegistrationPeer::findByUserId($userId);
 * ?>
 * </code>
 *
 * @see AbstractPeer
 * @see http://docs.google.com/Doc?docid=xxxx&hl=en
 *
 * @author xxx
 */
...