phpDocumentor

  개요
phpDocumentor(phpDoc)은 Java Documentor 처럼 PHP코드를 "문서화시키는 도구"입니다. php 코드의 주석에 들어있는 여러 태그들을 파싱하여 API 문서를 생성해주는 역할을 합니다.
(개인적으로는 주석없이 코드에 의도를 포함시키는 것을 더 선호 합니다;;;)

좋은 코드의 문서화를 하기 위해서는 사용자의 요구를 맞추는 게 중요합니다.
일반적인 소프트웨어 프로젝트를 바라보는 사용자들은 크게 두 분류로 나눌 수 있습니다.

• 하나는, 오픈소스를 사용하는 사람들로 내부의 코드가 어떻게 돌아가기보다는 인터페이스만을 알기를 원하는 사람들입니다.
  
• 또 다른 하나는, 오픈소스를 개발하는 사람들로 객체들이 어떻게 구성되어 있으며 어떻게 동작하는지를 확인하고 어떻게 확장할 지를 생각하는 사람들입니다.

각 사용자들의 요구에 맞추기 위해서 phpDoc은 html/chm/pdf 출력 포멧과 대상에 따른 출력 범위를 지정할 수 있습니다.
 
 특징
각 사용자들의 요구에 맞추기 위해서 phpDoc은 html/chm/pdf 출력 포멧과 대상에 따른 출력 범위를 지정할 수 있습니다.

• HTML, PDF, CHM, XML DocBook 생성
  
• 웹/커멘드 라인으로 실행가능
  
• 다양한 템플릿 기능 제공
  
• JavaDoc 포멧 뿐만 아니라 php를 위해 커스터마이징한 태그도 제공
  
• 자동 링크 생성기능과 클래스 상속 다이어그램과 오버라이드 명시
  
• README/CHANGELOG/INSTALL/FAQ 파일들을 파싱하여 문서안에 포함가능
  
• @TODO 태그를 사용하여 문서안에 TODO리스트를 생성
  
• @access, @internal 태그 사용 => 다중 문서 작성 가능
  
• Phpxref와 @example을 사용문서 안에 예제 파일 삽입가능
  
• 컨버터/usr.ini 사용 아웃풋 컨트롤 등

더 자세한 특징들은 tutorial을 참고해주세요.

 phpDocumentor 사용하기
기본적인 순서는 다음과 같습니다.

1. php 코드에 phpDoc으로 출력하기 위한 내용들을 주석에 작성을 합니다.
   
2. phpDoc을 생성하기 위한 입/출력 폴더를 지정합니다.
   
3. 프로그램을 시작하면, php파일을 컴파일 하면서
   
4. php 소스안에 정의되어 있는 tag들을 파싱하여서 문서로 생성합니다.

실행하는 방법에는 두 가지가 있습니다. 웹에서 실행하는 방법과 커맨드 상에서 phpdoc을 실행시키는 방법 두가지가 있습니다. (먼저, php가 설치되어 있어야하구요. 웹에서 실행하려면 apache가 설치되어 있어야 합니다.)

커맨드 상(윈도우 기준)에서 실행하려면 다음과 같이 명령어를 입력하면 됩니다.

C:\> phpdoc -o HTML:frames:earthli -f sample1.php -t docs

여기서 -o는 '출력 포멧'을 지정하며 -f는 '문서 생성 대상인 php 코드'명 -t는 '저장할 대상 폴더'를 지정합니다. 만약, 도움말이 필요하시다면 -h 또는 -help 옵션을 사용하면 상세하게 보실 수 있습니다.

C:\> php.exe phpdoc -h
C:\> php.exe phpdoc -help

웹상에서 실행하려면 phpdoc이 설치 된 폴더의 index.html을 브라우져로 엽니다.

상위의 메뉴를 보면 Config, Files, Output, Options, Credits, Links가 보이는데요. 각각은 phpDoc의 설정과 변환할 파일 경로 설정, 출력물 설정, 옵션 설정, 만든 사람들, 관련 링크가 들어있습니다.

실행을 하기 위해서는 다음과 같이 Files 옵션에서 변환할 코드의 경로를 입력합니다.

출력할 포멧 설정과 경로를 설정한 다음에 아래 쪽의 Create 버튼을 누르면 설정한 포멧 별로 html/pdf/chm(실제로는 chm 형태에 맞춰진 html이 생성)이 생성이 됩니다.

 주의할 점
phpDoc을 사용하여 문서를 작성할 때 주의하여야할 점들이 몇 가지 있습니다.

1. 기본 charset이 iso-8859-1로 설정되어 있어서 utf-8로 작성된 소스코드의 주석이 깨지는 문제가 있습니다. *.tpl 파일 들을 검색해서 utf-8로 변경해줘야 합니다. (phpDocumentor/Converters 아래의 파일들이 변환에 사용되는 템플릿 들입니다.)
   
2. 주석을 사용할 때 /* 로 시작되는 주석들은 문서로 생성이 되지 않습니다. /** 로 시작되어야지만 문서에 포함이 됩니다.
   
3. class에 속하는 주석은 class 바로 윗 줄에 작성되어져야 합니다. 떨어져 있는 경우 (주석과 class 키워드 사이에 다른 코드가 들어있는 경우) 해당하는 주석으로 처리되지 않고 생략이 됩니다.
   /**
    * 주석
    */
   class Test ...
   
4. 코드를 설명하는 글을 먼저 작성하고 태그가 나와야 합니다.
   /**
    * 이 코드는 어떤 코드입니다. Blah Blah~
    * @var string ...
    */
   
5. todo의 경우, @todo로 태그를 작성해야하며 class,function,var의 주석안에 포함되어야지만 보여집니다. 수정해야 될 코드에 @todo를 입력하는 경우 처리되지 않습니다.
   
6. php 코드 선언 부가 <? ?> 가 아닌 <?php ?>로 모두 선언되어야 합니다. 경우에 따라서는 안나오는 경우도 있네요.
   

관련 링크

• phpDocumentor - php 문서화 도구
  
• phpDocumentor Tags cheatsheet - PHPDoc의 태그들에 대한 요약 정리