문서화를 자동으로 XML 문서 주석

[ 서우석 2005/11/22]

여러분은 얼마나 많은 주석을 작성합니까? 그리고 주석을 어떤 용도로 사용하십니까? 주석을 작성해야 하는지, 또는 말아야 하는지에 대한 논의는 상당히 오랜 시간 동안 지속되어 왔으면서도 여전히 결론이 내려질 가능성이 그렇게 많지 않아 보이다. 그 옛날 소크라테스가 제자들에게 주석을 작성하는 것이 옳은가에 대한 질문을 했을 때, 한 제자는 코드의 유지 보수 측면에서 반드시 필요하다고 주장하고, 또 다른 제자는 코드가 모든 것을 말할 수 있어야 한다고 주장한다.

개인적으로는 매우 어려운 알고리즘이 아닌 이상 주석을 작성할 필요가 거의 없으며, 주석을 작성해야 할 만큼 복잡한 모듈은 리팩토링을 통해서 스스로를 설명할 수 있는(Self-Document) 보다 작은 모듈로 나누어져야 한다고 생각한다. 지금까지 이러한 논의가 끊이지 않았던 이유 중 하나는 주석이 코드 밖으로 나오지 못하고 코드 내에서만 존재한다는 가정이 있었기 때문이다. 만약 주석을 통해서 코드를 직접 살펴보지 않고 이해할 수 있을 정도의 문서화가 가능했다면, 아마도 주석이 그렇게 천대받지는 않았을 것이다.

C#은 개발자에게 주석을 작성할 것을 적극적으로 권장하고 있다. 그리고 개발자의 그러한 수고로움을 문서 파일(document file)이라는 형태로 보답한다. 문서 파일은 XML(Extensible markup Language) 포맷으로 주석을 작성하여 생성할 수 있다. 생성된 문서 파일의 포맷도 XML이기 때문에 사용자가 원하는 다른 형태로 변환이 가능하다. 비록 Visual Studio가 제공하는 ?IntelliSense 기능의 도움을 받으면 XML 주석을 보다 쉽고 빠르게 작성할 수 있지만, 문서 파일을 생성하는 기능은 C# 컴파일러의 기능(/doc 옵션)이기 때문에 Visual Studio가 없이도 소스 파일을 컴파일하는 것만으로도 생성이 가능하다.

주석 작성

C#에서 주석은 /* … */ 또는 // 으로 시작한다. 반면에 문서 주석은 /// 또는 /**로 시작한다. 문서 주석은 일반 주석과 달리 사용자 지정 타입(클래스, 델리게이트, 인터페이스)과 멤버(필드, 이벤트, 속성, 메서드)위에 작성되어야 한다. 앞서 설명했듯이, 문서 주석은 XML 포맷(http://www.w3.org/TR/REC-xml)을 따르기 때문에, 정형화된(well-formed) 형태를 유지해야 한다. 우선 간단한 예를 통해서 문서 주석의 실체를 확인해 보겠다.

/// <remarks><c>Point</c> 클래스는 2차원 상의 점(point)을 
/// 나타낸다.</remarks>
public class Point
{
  /// <remarks><c>draw</c> 메서드는 점을 그린다.</remarks>
  void draw() { }
}

이 코드에서 문서 주석을 작성하기 위해서 사용된 태그는 <remarks>와 <c>이다. 잠시 후에 문서 주석에 사용되는 태그들을 소개하겠지만, <remarks> 태그는 타입에 대한 설명을 기술하고, <c>는 코드로 나타낼 텍스트를 가리킨다. Visual Studio에서 문서화 파일을 생성하기 위해서는 다음 그림과 같이 프로젝트 옵션 창의 빌드 탭에서 XML document file 체크 상자를 선택한다.

그리고 Visual Studio는 문서 주석을 지원하므로, 주석을 추가하고자 하는 타입이나 멤버 위에서 ///를 입력하면 자동으로 <summary> 태그를 생성한다. 만약 기존에 작성된 주석에 새로운 태그를 추가하는 경우라면, 다음 그림과 같이 ?IntelliSense 기능이 활성화되어 상황에 맞는 태그를 선택할 수 있다.

주석을 작성하고 옵션을 설정한 후 빌드에 성공하면 Debug 폴더에 <프로젝트 이름>.xml과 같은 형태의 XML 파일이 생성됩니다. 다음 코드는 생성된 XML 파일 중에서 Point 클래스와 관련된 부분이다.

<member name="T:XMLDocument.Point">
  <remarks><c>Point</c> 클래스는 2차원 상의 점(point)을 나타냅니다.</remarks>
</member>
<member name="M:XMLDocument.Point.draw">
  <remarks><c>draw</c> 메서드는 점을 그립니다.</remarks>
</member>

<member>라는 새로운 태그가 추가된 점을 제외하면 원래 코드에 있던 태그들을 그대로 작성되었음을 확인할 수 있다. 생성된 XML 문서 주석은 XSLT(Extensible Stylesheet Language Transformation)등을 사용하여 새로운 형태의 문서로 변환이 가능하다.

문서 주석에 대한 권장 태그

문서 주석에 사용되는 태그는 제한이 없습니다(확장성 고려). 개발팀마다 원하는 태그를 만들어서 사용한 후, 생성된 XML을 재가공하여 사용하면 된다. 하지만 MS는 일반적으로 개발자에게 다음과 같은 태그들을 권장하고 있다.

NDoc을 이용한 도움말 파일 생성

지금까지 문서 주석이 무엇이고 문서 주석을 이용하여 XML 파일을 작성하는 방법에 대해서 살펴보았다. 마지막으로 생성된 XML 문서 파일을 이용하여 MSDN 라이브러리와 같은 도움말 파일을 생성하는 방법에 대해서 소개하겠다. XML 문서 파일을 도움말 파일로 변환하기 위해서 ?NDoc(http://ndoc.sourceforge.net)을 사용할 것이다. ?NDoc은 .NET 어셈블리와 XML 문서 파일을 사용하여 클래스 라이브러리 문서를 생성하는 툴이다(안타깝게도 .NET 2.0을 지원하지는 않기 때문에, ?NDoc을 실행하기 위해서 .NET 1.1 이하의 버전이 설치되어 있어야 한다).

NDoc을 설치한 후, 실행시키면 새로운 프로젝트가 생성됩니다. ?NDoc은 자체 프로젝트 파일을 관리하지만, Visual Studio 솔루션 파일(.sln)을 이용하여 새로운 프로젝트를 생성할 수 있기 때문에, 도움말 파일을 생성하고자 하는 솔루션 파일을 선택한다. 도움말 파일을 생성하기 전에, 여러 가지 옵션을 선택하여 최종 완성될 파일에 표시될 항목들을 선택할 수 있다. 다음 그림은 ?NDoc에서 ?XMLDocument 솔루션을 열었을 때의 모습이다.

설정을 완료 한 후, Document 메뉴의 Build 메뉴를 선택하면 도움말 파일을 생성하기 위한 빌드 작업이 시작되고, 최종 완성된 파일은 Document 메뉴의 View 메뉴를 선택하여 확인할 수 있다. 완성된 도움말 파일은 다음 그림과 같습니다. 한글이 지원되지 않아 깨지는 모습을 확인할 수 있다.