.NET 소스코드 문서화

소스코드 문서화

 

개발자들은 개발 문서작업을 진행하는 데 많은 노력과 시간을 투자한다.

직접 모든 비즈니스 로직이나 모듈을 문서로 작성하기란 만만치 않은 작업이다.

MSDN형태의 도움말을 구독성이 뛰어나고 쉽게 구현하는 방법이 있어 이를 소개하고자 한다.

 

우선 소스코드 문서를 XML 파일로 바꿔주는 C#컴파일러의 기능에 대해 알아보자.

C# 컴파일러가 코드 주석을 XML로 변경하는 과정을 담당한다.

소스코드 주석 : /// , /** */

 

이 XML 주석에서 사용하는 엘리먼트 정보들은 아래와 같다.

 

Element	정의
<c>	설명에 있는 텍스트를 코드로 표시하는 데 사용
<code>	여러 줄을 코드로 표시하는 데 사용
<example>	설명하고 있는 항목에 대한 코드 예제를 나타냄
<param>	파라미터를 설명한다
<remarks>	해당 멤버에 대한 설명을 작성하는 데 사용된다.
<returns>	멤버의 반환 값을 문서화한다.
<see>	관련된 항목들을 링크하는 데 사용한다.
<summary>	해당 항목에 대한 요약을 문서화 하는 데 사용한다.
<value>	해당 속성을 문서화하는데 사용한다.

[표 1]XML 주석 Element 설명

VS.NET 툴에서 기본적으로 IDE 기능들을 제공한다.

 

[그림 1]VS.NET에서의 XML 주석

 

[그림 1]처럼 메소드 앞에 ///를 3번 누르면 자동적으로 클래스나 메소드 및 필드에 맞는 element들이 생성되는 것을 볼 수 있다.

 

[그림 2] VS.NET에서의 XML 주석

이것 외에 부연 설명이나 예제코드, 참고자료 등을 작성하고 싶을 경우에는 [그림 2]처럼 element를 추가하여 작성할 수 있다.

 

소스 코드에 네임스페이스, 클래스, 메소드나 멤버 변수에 XML 주석을 작성을 다 했으면 컴파일 시 /doc 옵션을 이용해 XML 문서를 추출해야 한다.

 

VS.NET 에서 프로젝트명 – 속성 – 빌드 탭에 XML문서 파일 설정을 체크하고 저장한다.

[그림 3] VS.NET을 이용하여 XML 문서 출력

 

[그림 3]와 같이 설정한 후 컴파일을 하게 되면  bin\Debug\ePlayon.Batoo.BLL.XML 파일에 주석 문서가 생성된다.

아래 그림은 문서의 내용을 일부 발췌하였다.

 

[그림 4] XML 문서 형식

 

파란색으로 표시된 내용을 보면 M:, T:와 같은 포맷 문자가 있다.

아래 [표 2]는 포맷 문자를 정리한 것이다.

 

Element	정의
N	네임스페이스
T	형식(클래스, 인터페이스, 구조체, 열거형, 델리게이트)
F	필드
P	형식 속성
M	메소드(생성자와 오버로드된 연산자 포함)
E	이벤트
!	에러에 대한 정보를 나타내는 에러 문자열

[표 2]XML 주석 포맷 문자

C# 컴파일러를 통해 생성된 이 xml 파일은 사용자 도움말 형태로 변환하기 위한 xml 정의 파일이라 할 수 있다.

그럼 사용자 도움말 형태로 만들기 위해 마이크로소프트에서 프리웨어로 제공하는 sandcastle 이라는 프로그램을 사용하여 작업을 진행해 보자.

Microsoft의 개발자들이 자신들이 도움말을 만들 때 사용하는 툴을 공개하였는데 그것이 바로 Sandcastle 이다.

Sandcastle 을 설치하기에 앞서 도움말 형태의 뷰어를 설치해야 한다.

아래 링크에서 HTML Help workshop 과 sandcastle, 그리고 sandcastle UI 프로그램을 다운받아 차례로 설치하자.

 

Microsoft HTML Help Downloads :

http://go.microsoft.com/fwlink/?linkid=14188

 

sandcastle Downloads:

http://www.codeplex.com/Sandcastle/Release/ProjectReleases.aspx?ReleaseId=9921

 

sandcastle help file builder Downloads :

http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx?ReleaseId=9848

 

Sandcastle 원리

 

[그림 5] Sandcastle 처리 원리

 

[그림 5]은 sandcastle이 내부적으로 소스코드를 문서화 해주는 과정을 나타내고 있다.

우선 VS.NET 툴에서 컴파일 시 XML 문서 파일을 출력하도록 하는 명령이 csc /doc 임을 알 수 있다. 컴파일이 성공하면 바이너리 폴더에 dll 파일과 xml 파일이 생성된다.

이때 SandCastle 의 BuildAssembler 에서 xml 파일과 dll 파일을 분석하여 필요한 정보들을 생성한 후 이 결과를 HTML Help Compiler에서 컴파일하여 도움말 형태로 출력시킨다.

 

그럼 sandcastle 툴을 사용하여 직접 소스 코드 도움말을 생성해보자.

앞서 봤듯이 dll 파일과 xml 파일은 있다는 가정 하에 테스트를 진행해 보겠다.

Sandcastle Help File Builder에서 “Sandcastle Help File Builder GUI” 를 실행시킨다.

 

[그림 6] Sandcastle Help File Builder 메인 화면

 

[그림 6]은 Sandcastle의 기본 UI 이다. Add 버튼을 이용하여 바이너리(dll) 파일을 등록할 수 있다.

하지만 테스트할 바이너리는 웹 사이트의 모든 참조 라이브러리 프로젝트를 생성해야 하므로 수동으로 직접 입력하는 방법보다 솔루션 파일을 이용해 도움말을 생성해 보도록 하겠다.

 

[그림 7] 솔루션 파일로 어셈블리 참조

 

[그림 7]에서 보듯이 Project 메뉴에 New Project from Visual Studio Project… 를 실행하여

솔루션 파일을 바인딩 시켜보자.

 

[그림 8] 솔루션 파일로 바인딩 시 선택화면

 

솔루션 파일을 등록하게 되면 [그림 8]과 같이 나오면 Select 를 클릭한다.

 

[그림 9] 솔루션 파일로 바인딩 시 UI

 

[그림 9]에서 보듯이 관련 참조된 어셈블리와 XML파일들이 바인딩 되는 것을 볼 수 있다.

이제 모든 준비가 끝이 났다.

 

우선 현재 sandcastle 프로그램을 저장하여 파일명.shfb파일을 도움말을 설치할 폴더에 저장한 후

Documentation 메뉴에 Build Project를 실행시켜보자.

 

[그림 10] 도움말 생성 컴파일

 

[그림 10]의 아래 Output에서 보듯이 성공적으로 컴파일을 완료하였다.

저장한 폴더의 Help 폴더에 보면 Documentation.chm 파일이 생성된 것을 확인할 수 있다.

 

[그림 11] 도움말 생성 UI

 

[그림 11]에서 보듯이 성공적으로 도움말이 생성된 것을 확인하였다.

객체의 구조와 각 네임스페이스, 클래스, 메소드, 필드, 속성별로 설명이 되어 있다.

출처 : 허둥사마