LazarusCompleteGuide:1.6
소스 코드 문서화
파스칼 코드는 본질적으로 가독성이 높지만 코드는 문서화되어야 한다. 코드 문서화의 한 가지 방법은 주석문(comment)를 쓰고 특수 문자로 표기하여 pasdoc 과 같은 툴이 주석문으로부터 문서를 생성하는 방법이다. 하지만 pasdoc을 이용하면 소스 코드 내에 실행 가능한 예나 완전한 설명을 포함할 수 없다. 이러한 이유로 인해 프리 파스칼에서는 FPDoc 툴을 제공한다. 각 유닛마다 해당 툴은 XML 파일을 생성하는데, 이 파일에는 각 식별자에 대한 간략한 설명, 해설, 예, 링크, 기타 정보를 묶을 수 있다. FPDoc는 HTML 포맷팅 태그(formatting tag)의 부분집합(subset)을 지원한다.
FPDoc은 매우 유연하고 확장 가능하게 고안되었으며, 다양한 출력 모듈을 포함한다. 현재 Latex, HTML, PDF, chm에서 모듈을 이용 가능하다.
라자루스 0.9.24 버전에서는 다큐멘테이션 에디터(Documentation Editor)가 소개되었는데, 이는 XML 요소를 간편한 트리 구조로 표시하여 다수의 FPDoc XML 파일을 편집하는 데 사용된다. IDE용의 간단한 통합 에디터도 포함되어 있으며, 소스 코드에서 선택된 식별자에 상응하는 FPDoc XML 파일 내 엔트리를 보여주고 간단한 변경을 허용한다.
그 이후로 통합 에디터는 확장되어 현재 FPDox XML 파일을 자동으로 생성하여 거의 모든 속성을 편집할 수 있게 되었다. FPDoc 에디터는 View ⇒ FPDoc Editor를 선택하여 표시할 수 있다. 커서가 소스 코드 내 식별자에 위치한 경우, 에디터가 처음에는 해당 엔트리가 아직 존재하지 않는다고 표시한다. Create help item 버튼을 클릭하면 디렉터리 대화창이 열린다.
FPDoc 파일에 대해 패키지 또는 프로젝트 디렉터리 내에 구분된 하위디렉터리(폴더)가 생성되어야 하는데, doc 이라는 이름을 예로 들 수 있겠다. 이러한 하위디렉터리는 Package 대화창의 Options ⇒ IDE Integration ⇒ FPDoc files path 에서 경로를 설정하고 유닛 이름으로 된 첫 번째 FPDoc 파일을 생성한다. 현재 프로젝트의 유닛에 대해서도 동일한 프로시저를 이용할 수 있다. 이는 프로그래머들이 직접 문서를 생성하도록 해주며 IDE에서는 즉시 문서가 표시된다. 예를 들어, 마우스 포인터를 식별자 위를 맴돌면 IDE는 해당 식별자에 대한 모든 주석문, pasdoc 주석문, FPDoc의 간략한 설명을 전부 표시한다.
IDE는 모든 조상들과 오버로딩된(overloaded) 프로시저를 자동으로 검색하여 도움말 정보를 표시하기도 한다. 다시 말해, 기반 클래스(base class)만 문서화해도 충분하다는 의미로, 파생된 모든 클래스들은 그 결과 자동적으로 문서화된다. 전체 도움말 파일을 HTML, PDF, Latex 또는 CHM 형식으로 XML 파일로부터 생성하기 위한 프로시저는 프리 파스칼 웹사이트 ( http://www.freepascal.org/docs.var )의 'fpdoc documentation tool reference manual'에 실린 FPDoc 설명에 자세히 나와 있다.
