[RedBook C#] 문서 자동화편

http://kaistizen.net/EE/index.php/weblog/comments/redbook_csharp_documentation/
좋은 자료가 있어서 퍼왔습니다.

2007.03.21 알립니다. PDF로도 제공합니다.

주의! RedBook은 SK-imedia에서 인턴으로 일하는 와중에 작성한 문서입니다. 내부 시스템이나 전략과 관련된 정보는 공개 못합니다. 하지만 RedBook은 프로그래밍 가이드이고 이런 정보와는 전혀 상관 없습니다. 사실 공개 못하는 내용이 100배는 흥미로운데 안타깝기도 하군요. ^^

얼마 전부터 MS 워드 2007을 사용하게 됐는데, 사용자 인터페이스의 변화는 실로 혁명적이었습니다. 그래서 문서를 웹 편집기가 아닌 워드 2007로 작성했습니다. 이번에는 처음 공개하는 것이니 HTML로 변환하긴 했습니다만, 개정될 내용은 docx 파일로만 배포할 것 같습니다.

MS Word 2007 문서 다운로드¹

이 문서는 Visual Studio 2005를 기준으로 작성되었다. 어떻게 하면 최소한의 투자만으로 훌륭한 문서를 작성할 수 있을지 고민인 개발자를 위해 가이드라인을 제시하는 것이 목표이다.

XML 주석

Visual Studio 2003부터 XML 주석이 도입되었다. 이 멋진 IDE는 사용자를 배려하는 매너까지 보여준다. 클래스나 메써드 등의 바로 위에서 '/'를 연속 세 번 누르면 다음과 같이 XML 주석이 생성된다.

소스코드 1. XML 주석

undefined²undefined²undefined²view plain²copy to clipboard²print²?²

1. /// <summary>  
2. ///   
3. /// </summary>  
4. /// <param name="source"></param>  
5. /// <param name="e"></param>  
6. public static void AppThreadException(object source, UnhandledExceptionEventArgs e)  
7. {  
8. }  

/// <summary> /// /// </summary> /// <param name="source"></param> /// <param name="e"></param> public static void AppThreadException(object source, UnhandledExceptionEventArgs e) { }

빈 칸에 메써드와 매개변수에 대한 설명 글을 써 넣기만 하면 된다. 이렇게 작성된 주석은 XML 문서로 변환하여 MSDN과 같은 멋진 클래스 명세서를 만드는데 사용된다. 물론 이 모든 작업은 자동화가 가능하기 때문에 여러분의 귀중한 시간을 잡아먹지도 않는다.

그림 1. 자동 생성된 클래스 명세서 예제

⁴³

권장 태그

‘/’ 세 번 누르면 기본적인 XML 주석 템플릿을 생성해주지만, 그것이 전부라고 생각하면 오산이다. 훗날 Sandcastle과 같은 문서화 도구를 사용했을 때, 멋진 결과물을 보고 싶다면 최대한 태그를 활용해야 한다.

MSDN에서 문서 주석에 대한 권장 태그라는 키워드로 검색하면 어떤 태그를 사용하면 되는지 알 수 있을 것이다. 약 20개의 태그가 있기 때문에 여기서 지면을 할애하여 설명하기는 무리다. 그러니 예제를 몇 개 제시하는 것으로 대신하겠다.

소스코드 2. 문서 주석 예제 I

undefined²undefined²undefined²view plain²copy to clipboard²print²?²

1. /// <summary>  
2. /// <para>플러그인 로드 및 해제 등의 관리 기능을 제공한다.</para>  
3. /// </summary>  
4. /// <remarks>  
5. /// <para>플러그 구현을 위해 다음 문서를 참고했다. </para>  
6. ///   
7. /// <list type="bullet">  
8. /// <listheader>참고 문헌</listheader>  
9. /// <item>  
10. /// <description>Plug-ins in C#  by Redth. </description>  
11. /// </item>  
12. /// </list>  
13. /// </remarks>  
14. public sealed class PluginManager  
15. {  
16. 중략……  
17. }  

/// <summary> /// <para>플러그인 로드 및 해제 등의 관리 기능을 제공한다.</para> /// </summary> /// <remarks> /// <para>플러그 구현을 위해 다음 문서를 참고했다. </para> /// /// <list type="bullet"> /// <listheader>참고 문헌</listheader> /// <item> /// <description>Plug-ins in C# by Redth. </description> /// </item> /// </list> /// </remarks> public sealed class PluginManager { 중략…… }

소스코드 3. 문서 주석 예제 2

undefined²undefined²undefined²view plain²copy to clipboard²print²?²

1. /// <summary>  
2. /// <para>특정 확장자를 가진 파일을 업로드 할 수 있는지 확인한다.</para>  
3. /// </summary>  
4. /// <param name="fileExtension">이미지 파일의 확장자</param>  
5. /// <returns>업로드 가능 여부</returns>  
6. /// <example>  
7. /// <code>  
8. /// FileUploader uploader = CreateFileUploader();  
9. /// if( uploader.CanUpload( "jpg" ) == false )  
10. /// {  
11. ///     Console.WriteLine( "Can not upload '*.jpg' files." );  
12. /// }  
13. /// </code>  
14. /// </example>  
15. /// <seealso cref="FtpFileUploader"/>  
16. /// <seealso cref="HttpFileUploader"/>  
17. public abstract bool CanUpload(string fileExtension);  

/// <summary> /// <para>특정 확장자를 가진 파일을 업로드 할 수 있는지 확인한다.</para> /// </summary> /// <param name="fileExtension">이미지 파일의 확장자</param> /// <returns>업로드 가능 여부</returns> /// <example> /// <code> /// FileUploader uploader = CreateFileUploader(); /// if( uploader.CanUpload( "jpg" ) == false ) /// { /// Console.WriteLine( "Can not upload '*.jpg' files." ); /// } /// </code> /// </example> /// <seealso cref="FtpFileUploader"/> /// <seealso cref="HttpFileUploader"/> public abstract bool CanUpload(string fileExtension);

XML Comments로 주석 편하게 달기

Visual Studio가 메써드에 맞춰서 주석 템플릿을 생성해준다고 해도 문서화는 여전히 고된 작업이다. 추상클래스 AbstractBlogClient 와 이것을 상속 받은 TatterToolsClient가 있다고 가정해보자. TatterToolsClient는 오버라이딩된 Connect라는 메써드를 가지고 있는데, 부모 클래스의 주석이 이 메써드의 역할을 잘 설명하고 있다. 그럼에도 불구하고 여러분은 똑 같은 주석을 자식 클래스에 복사해 넣어야 한다. 이 무슨 삽질이란 말인가? 하지만 방법이 없다. 제대로 된 문서를 생성하기 위해선 이 방법뿐이다. XML Comments가 없다면 그렇다는 것이다.

소스코드 4. XML Comments의 적용 사례

undefined²undefined²undefined²view plain²copy to clipboard²print²?²

1. /// <summary>현재 <see cref="T:System.Object"></see>를 나타내는 <see cref="T:System.String"></see>을 반환합니다.</summary>  
2. /// <returns>현재 <see cref="T:System.Object"></see>를 나타내는 <see cref="T:System.String"></see>입니다.</returns>  
3. /// <filterpriority>2</filterpriority>  
4. public override string ToString()  
5. {  
6.     return "Homepage URL: " + _hompageUrl + Environment.NewLine;  
7. }  

/// <summary>현재 <see cref="T:System.Object"></see>를 나타내는 <see cref="T:System.String"></see>을 반환합니다.</summary> /// <returns>현재 <see cref="T:System.Object"></see>를 나타내는 <see cref="T:System.String"></see>입니다.</returns> /// <filterpriority>2</filterpriority> public override string ToString() { return "Homepage URL: " + _hompageUrl + Environment.NewLine; }

시스템 요구 사항

제작자가 배포한 README.TXT 파일에 따르면 Visual Studio .NET 2003과 Visual Studio 2005 Beta 2에서 테스트를 마쳤다고 한다. Visual Studio 2005 정식 버전에서 정상적으로 작동하는 것을 직접 확인했다.

설치 요약

1. Visual Studio 2005 실행

2. Alt + F11 단축키

3. 'MyMacros' 프로젝트에 XmlCommentMacros.vb 파일 추가

4. 'MyMacros' 프로젝트에 System.Xml 어셈블리 참조 추가

설치

Document Your Code in No Time At All with Macros in Visual Studio⁵에서 XMLComments.exe 파일을 다운로드 받는다. 파일을 실행시키면 WinZip Self-Extractor가 어느 폴더에 압축을 풀 것인지 묻는다. 어떤 경로라도 상관 없지만, 여기서는 Temp\XMLComments를 선택했다. 폴더에는 다음과 같은 파일이 있을 것이다.

• EULA.doc: 최종 사용자 라이선스 협정

• README.TXT: 설치 관련 문서

• XmlCommentMacros.vb: Visual Studio 매크로

Visual Studio 2005을 실행시킨다. [도구/매크로/매크로 IDE] 선택하거나 Alt+F11 단축키를 누른다. 매크로 IDE가 열리면, '프로젝트 탐색기'에 'MyMacros', 'Samples' 두 개의 프로젝트를 확인할 수 있다. 새로운 프로젝트를 생성해도 되지만, 여기서는 'MyMacros'에 매크로를 추가한다. 'MyMacros' 위에 커서를 놓는다. 컨텍스트 메뉴를 열고, [추가/기존 항목 추가]를 선택한다. XmlCommentMacros.vb 를 추가하자.

그림 2. XML Comments 등록하기

⁷⁶

추가 작업

매크로 설치는 끝났다. 하지만 한 가지 작업을 더 해 주어야 인생이 편해진다. 가끔 쓰는 매크로라면 필요할 때마다 매크로 탐색기를 열어서 실행시키면 된다. 하지만 주석 작업을 하는 내내 매크로 탐색기와 솔루션 탐색기 사이를 오가고 싶지는 않을 것이다. 그러니 매크로에 바로 가기 키를 할당할 필요가 있다.

바로 가기 키를 부여하려면 [도구 / 사용자 지정 / 키보드]를 순서대로 선택한다. [그림 3]과 같은 화면을 보게 될 것이다. 화면에 제시된 바대로 설정해준 다음 ‘바로 가기 키 누르기’에 적절한 바로 가기 키를 눌러주기만 하면 된다. 여기서는 다음과 같이 바로 가기 키로 설정했다.

• DocumentConstructor: Alt + o

• DocumentExceptions: Alt + e

• InheritDocumentation: Alt + i

그림 3. 매크로에 핫키 할당하기

⁹⁸

실습하기

생성자에 주석 달기

이제 XMLComments를 사용하여 실습해보자. 우선 아무 클래스의 생성자나 선택하자. 여기서는 BlogPost라는 클래스를 골랐다. 생성자 이름에 커서를 올려놓은 후, 앞서 할당한 바로 가기 키 Alt + o 를 누르자.

소스코드 5. 주석 없는 생성자

undefined²undefined²undefined²view plain²copy to clipboard²print²?²

1. public BlogPost()  
2.     : this(string.Empty, string.Empty)  
3. {  
4. }  

public BlogPost() : this(string.Empty, string.Empty) { }

Alt + o 키를 누르자마자 다음과 같이 아름다운 주석이 자동 생성된다. 혹자는 영어로 주석이 달려서 마음에 들지 않을지 모르겠다. 하지만 걱정 마시라. 매크로 IDE에서 ‘Initializes’로 검색하면 해당 문자열을 찾을 수 있으니 직접 수정하면 된다.

소스코드 6. 주석 달린 생성자

undefined²undefined²undefined²view plain²copy to clipboard²print²?²

1. /// <summary>  
2. ///     <para>Initializes an instance of the <see cref="BlogPost"/> class.</para>  
3. /// </summary>  
4. public BlogPost()  
5.     : this(string.Empty, string.Empty)  
6. {  
7. }  

/// <summary> /// <para>Initializes an instance of the <see cref="BlogPost"/> class.</para> /// </summary> public BlogPost() : this(string.Empty, string.Empty) { }

예외를 발생시키는 프로퍼티에 주석 달기

자, 이번에는 예외를 발생시키는 프로퍼티를 하나 골라보자. 그리고 조금 전과 같이 바로 가기 키를 눌러보자. 단, 이번에는 Alt + e 키를 누르는 것만 다르다.

소스코드 7. <exception> 주석 없는 프로퍼티

undefined²undefined²undefined²view plain²copy to clipboard²print²?²

1. /// <summary>  
2. /// <para>블로그 엔진 또는 서비스를 제공하는 <see cref="IBlogClient" /> 구현의 타입을 나타낸다.</para>  
3. /// </summary>  
4. /// <value>블로그 엔진 또는 서비스를 제공하는 <see cref="IBlogClient" /> 구현의 타입을 설정하거나 반환한다.</value>  
5. public Type ClientType  
6. {  
7.     get { return _clientType; }  
8.     set 
9.     {  
10.         if(value.GetInterface( "IBlogClient" ) == null)  
11.         {  
12.             throw new ArgumentException();  
13.         }  
14.         _clientType = value;  
15.     }  
16. }  

/// <summary> /// <para>블로그 엔진 또는 서비스를 제공하는 <see cref="IBlogClient" /> 구현의 타입을 나타낸다.</para> /// </summary> /// <value>블로그 엔진 또는 서비스를 제공하는 <see cref="IBlogClient" /> 구현의 타입을 설정하거나 반환한다.</value> public Type ClientType { get { return _clientType; } set { if(value.GetInterface( "IBlogClient" ) == null) { throw new ArgumentException(); } _clientType = value; } }

소스코드 8. <exception> 주석 달린 프로퍼티

undefined²undefined²undefined²view plain²copy to clipboard²print²?²

1. /// <summary>  
2. ///     <para>블로그 엔진 또는 서비스를 제공하는 <see cref="IBlogClient" /> 구현의 타입을 나타낸다.</para>  
3. /// </summary>  
4. /// <value>블로그 엔진 또는 서비스를 제공하는 <see cref="IBlogClient" /> 구현의 타입을 설정하거나 반환한다.</value>  
5. /// <exception cref="ArgumentException">  
6. /// </exception>  
7. public Type ClientType  
8. {  
9.     get { return _clientType; }  
10.     set 
11.     {  
12.         if(value.GetInterface( "IBlogClient" ) == null)  
13.         {  
14.             throw new ArgumentException();  
15.         }  
16.         _clientType = value;  
17.     }  
18. }  

/// <summary> /// <para>블로그 엔진 또는 서비스를 제공하는 <see cref="IBlogClient" /> 구현의 타입을 나타낸다.</para> /// </summary> /// <value>블로그 엔진 또는 서비스를 제공하는 <see cref="IBlogClient" /> 구현의 타입을 설정하거나 반환한다.</value> /// <exception cref="ArgumentException"> /// </exception> public Type ClientType { get { return _clientType; } set { if(value.GetInterface( "IBlogClient" ) == null) { throw new ArgumentException(); } _clientType = value; } }

보다시피 ArgumentException에 대한 주석이 추가됐다. 이 매크로는 메써드가 던질지 모르는 예외가 여러 개이더라도, 모든 예외에 대한 주석을 추가해준다.

상속 받은 메써드에 주석 달기

이제 요령이 생겼으리라 믿는다. 이번에는 오버라이딩한 메써드를 하나 찾아서 Alt + I 키를 눌러보자.

소스코드 9. 주석 없는 ToString()

undefined²undefined²undefined²view plain²copy to clipboard²print²?²

1. public override string ToString()  
2. {  
3.     string msg = "POST ID: " + postId + Environment.NewLine;  
4.     return msg;  
5. }  

public override string ToString() { string msg = "POST ID: " + postId + Environment.NewLine; return msg; }

소스코드 10. 주석 달린 ToString()

undefined²undefined²undefined²view plain²copy to clipboard²print²?²

1. /// <summary>현재 <see cref="T:System.Object"></see>를 나타내는 <see cref="T:System.String"></see>을 반환합니다.</summary>  
2. /// <returns>현재 <see cref="T:System.Object"></see>를 나타내는 <see cref="T:System.String"></see>입니다.</returns>  
3. /// <filterpriority>2</filterpriority>  
4. public override string ToString()  
5. {  
6.     string msg = "POST ID: " + postId + Environment.NewLine;  
7.     return msg;  
8. }  

/// <summary>현재 <see cref="T:System.Object"></see>를 나타내는 <see cref="T:System.String"></see>을 반환합니다.</summary> /// <returns>현재 <see cref="T:System.Object"></see>를 나타내는 <see cref="T:System.String"></see>입니다.</returns> /// <filterpriority>2</filterpriority> public override string ToString() { string msg = "POST ID: " + postId + Environment.NewLine; return msg; }

보다시피 부모 클래스의 주석을 가져왔다. ToString()처럼 설명을 달리 해야 할 필요가 없을 때 아주 편리한 기능이다. Copy & Paste와는 이제 안녕이다.

Sandcastle로 클래스 명세서 만들기

NDoc 프로젝트의 최후

좋았던 시절

과거엔 많은 사람들이 NDoc¹⁰이라는 문서 자동생성 도구를 사용했었다. XML 주석만 있으면 MSDN과 같은 멋진 문서를 자동으로 생성해주었기에 인기가 많았다. 더구나 오픈 소스 프로젝트의 산물이었기 때문에, 비용 지불을 하지 않아도 됐었다. 그래서 마땅한 문서화 도구가 없었던 Visual Studio.NET 2003 시절에는 NDoc이 대세였다.

최후를 맞이하다.

하지만 안타깝게도 이 멋진 프로젝트는 공식적으로 중단되었다. 프로젝트가 중단된 이유는 역시나 참여자가 너무나 적었기 때문이다. 자세한 내용을 알고 싶다면 Sandcastle - Microsoft CTP of a Help CHM file generator on the tails of the death of NDoc¹¹을 읽어보기 바란다.

공식 릴리즈된 가장 마지막 NDoc이 .NET Framework 2.0을 지원하지 않기 때문에 더 이상 NDoc을 사용할 일은 없을 것이다. 물론 편법은 있다. 개발 중이던 NDoc 2005¹²를 내려 받아서 빌드하면 된다. (참고 문서: Visual Studio 2005 - Documentation Generation Using NDoc 2005¹³) 하지만 더 좋은 도구가 있으니 그만두라고 말리고 싶다.

한글 환경에서 NDoc 을 사용하기 위해선 반드시 알아야 할 사항이 서너 가지 있다. 그러므로 NDoc 프로젝트 사이트¹⁰의 User's Guide¹⁴만으론 충분치 않을 수 있다. NDoc 관련 문서¹⁵를 참조해서 작업해야만 한다.

Sandcastle이란?

앞서 열심히 XML 주석을 달았다. 하라고 해서 죽어라 주석을 달았는데 왜 해야 하는지 몰랐다면 이제부터 알게 될 것이다. [그림 1]은 Sandcastle로 만든 문서이다. XML 주석만 있다면 이런 멋진 문서를 작성하는 것쯤은 누워서 떡 먹기 보다 쉽다.

Sandcastle은 마이크로소프트가 무료로 배포하는 소프트웨어이니, 돈 걱정할 필요가 없다. 게다가 마이크로소프트 내부 개발팀에서도 사용한다는 후문이 들리는 것으로 보아 지속적인 업데이트도 기대할 수 있다.

Sandcastle 설치 요약

1. Sandcastle¹⁶ 설치

2. Sandcastle Help File Builder¹⁷ 설치

Sandcastle 설치하기

우선 Sandcastle¹⁶부터 다운로드 받자. 현재 최신 버전은 Sandcastle - December 2006 Community Technology Preview (CTP)¹⁸이다. Windows Installer를 실행시켜서 설치하자. 설치 과정이 끝났으니 바탕화면을 본다. 아무것도 없다. 진짜 아무것도 없다. 바로 가기 아이콘이고 뭐고 없다. CTP 버전이라 봐준다.

Program Files\Sandcastle에 Sandcastle이 설치되어 있다. 궁금하니 이것저것 실행시켜본다. 하지만 죄다 콘솔 애플리케이션이고 GUI는 어디에도 없다. 안타깝게도 현재는 콘솔 모드만 지원한다. 이것도 CTP 버전이니 봐주자. 그러나 좌절할 필요는 없다. 여러분만 짜증나는 게 아니다. 진작에 마이크로소프트답지 않은 작태에 화가 났던 이들이 있었다. 그들이 여러분 대신 GUI 인터페이스를 개발해놨다.

Sandcastle Help File Builder¹⁷을 다운로드 받아 설치하자.

여러분이 영문 Visual Studio 2005를 사용하고 있다면 Visual Studio 2005 Add-In Suite with Sandcastle¹⁹도 설치해볼 일이다. 불행히도 현재 버전은 한글판에서 제대로 작동하지 않는다.

이제 설치 끝이다. 이제 한번 멋진 문서를 만들어보자.

Sandcastle로 문서 빌드하기

가장 먼저 할 일은 프로젝트의 빌드 설정 값을 확인하는 것이다. [그림 4]에서와 같이 XML 문서 파일 체크 박스를 선택해주자. 이제 빌드를 하면 출력 경로에 프로젝트 이름.xml 파일이 있을 것이다. 프로젝트 이름이 Cooking이라면 출력 경로엔 Cooking.dll, Cooking.pdb 파일과 함께 Cooking.XML 파일이 있을 것이다.

그림 4. XML 문서 파일 생성하기

²¹²⁰

자, 이제 Sandcastle Help File Builder¹⁷를 실행시키자. 친숙한 화면이다. NDoc과 거의 유사한데 오히려 설정해야 할 것은 줄어들었다. HelpTitle이나 FeedbackEMailAddress 정도만 바꾸어주고 그대로 사용하면 된다. Language에 한글이 없지만 영어로 해놔도 전혀 문제가 없다.

프로젝트 어셈블리 파일과 XML 문서파일을 추가(Add)하고 [Documentation / Build]를 선택하면 끝이다. 이제 완성된 문서를 보고 흐뭇한 미소를 지으면 된다.

그림 5. Sandcastle Help File Builder

²³²²

업데이트 계획

• #region 및 자동화 (코드 스니핏, 매크로)

• GhostDoc

• Automating the code writing process using macros²⁴

Links

1. http://kaistizen.net/EE/images/uploads/RedBook.zip
2. http://kaistizen.net/EE/index.php/weblog/comments/redbook_csharp_documentation/#
3. http://www.flickr.com/photos/kaistizen/420115898/
4. http://farm1.static.flickr.com/173/420115898_192be1a79b.jpg
5. http://msdn.microsoft.com/msdnmag/issues/05/07/XMLComments/default.aspx
6. http://www.flickr.com/photos/kaistizen/420115921/
7. http://farm1.static.flickr.com/176/420115921_32bc396f86_o.png
8. http://www.flickr.com/photos/kaistizen/420115958/
9. http://farm1.static.flickr.com/147/420115958_fa8399d2d6.jpg
10. http://ndoc.sourceforge.net/
11. http://www.hanselman.com/blog/SandcastleMicrosoftCTPOfAHelpCHMFileGeneratorOnTheTailsOfTheDeathOfNDoc.aspx
12. http://sourceforge.net/projects/ndoc05/
13. http://geekswithblogs.net/sudheersblog/archive/2006/07/24/86146.aspx
14. http://ndoc.sourceforge.net/usersguide.html
15. http://kaistizen.net/EE/index.php/weblog/comments/ndoc/
16. http://blogs.msdn.com/sandcastle/
17. http://www.codeplex.com/SHFB
18. http://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2
19. http://www.codeplex.com/SandcastleAddIn
20. http://www.flickr.com/photos/kaistizen/420115983/
21. http://farm1.static.flickr.com/150/420115983_74a16070d9.jpg
22. http://www.flickr.com/photos/kaistizen/420116022/
23. http://farm1.static.flickr.com/166/420116022_bc68696295.jpg
24. http://www.codeproject.com/csharp/documentatormacros.asp