PHPDOC 생성 문서와 함께 높은 수준의 문서를 어떻게 유지합니까?

Question

첫 번째 오픈 소스 프로젝트 (뻔뻔한 플러그 : Mtchart) 현재 두 가지 유형의 문서가 있습니다.

• 코드 내에서 phpdoc-comments에서 doxygen에 의해 생성 된 HTML 파일
• Google 코드의 Wiki 페이지 (또는 간단히 말해 : 추가 텍스트 파일)

Doxygen 파일은 정말 훌륭하지만 '고급'문서를 추가 할 가능성이 없습니다 : 튜토리얼, 예제, 시스템에 대한 개요, 로드맵 등.

이 두 가지를 자동화 된 방식으로 어떻게 결합하여 코드 문서를 나머지 텍스트를 포함하여 어떻게 든 자동으로 업데이트 할 수 있습니까?

(필요한 경우 Doxygen에서 멀리 이동하려고합니다.)

Answer 1

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
 */