C# XML 주석 사용하기
프로그래밍 코딩에 있어서 주석의 필요성 및 깊이에 대해 많은 찬반 논란이 있다. 많은 부분에서 원인을 찾을 수 있지만 그 중 하나는 소스 코드 상의 주석이 코드 밖으로 나올 수 없기 때문이다.
C# 은 개발자에게 주석을 작성할 것을 적극 권장하고 있다. 즉, 소스 코드에서 작성한 주석이 소스 코드 밖으로 문서화 되어 생성된다. 모든 주석 형식( /*…*/, //) 문서화 될 수 있는 것은 아니다.
C# 에서는 XML 태그 주석을 지원한다. XML 태그로 작성된 주석은 C# 컴파일러에 의해 “문서 파일 (Document File)” 이라는 파일을 생성시켜준다. 생성된 문서 형태가 XML 이기 때문에 사용자가 원하는 다른 형태로 변환 가능하다.
■ 문서 주석
1. 문서 주석의 시작
/// 또는 /** 형태로 시작
2. 문서 주석의 위치
일반 주석과 달리 문서 주석을 사용할 수 있는 부분이 정해져 있다. 아래와 같은 부분 위에 문서 주석을 작성할 수 있다.
- 사용자 지정 타입 (클래스, 델리게이트, 인터페이스)
- 멤버 (필드, 이벤트, 속성, 메서드)
3. 문서 주석은 XML 포멧을 따르기 때문에 정형화된 형태를 유지해야 한다.
■ 문서 주석 설정
1. 프로젝트 -> 속성 -> 빌드
WinForm 프로젝트 생성 시 기본적으로 선택되어 있지 않는다.
■ 문서 주석 작성
Visual Studio 2008 은 문서 주석을 인텔리센스로 지원 한다. “/” 을 세번 입력하면 문서 주석의 틀을 자동으로 삽입해 준다.
■ 문서 주석 출력 예
< 문서 주석이 작성된 코드 >
< 출력된 *.XML 파일 >
■ XML 태그 종류
문서 주석에 사용되는 태그에는 제한이 없다. MS 에서 권장하는 태그는 다음과 같다. 자세한 사용 방법은 MSDN 을 참조
<c>
설명에 있는 텍스트를 코드로 표시하는데 사용
<code>
여러 줄을 코드로 표시하는데 사용
<example>
메서드나 기타 라이브러리 멤버의 사용 방법에 대한 예제를 지정
<include>
소스 코드의 형식과 멤버를 설명하는 다른 파일의 주석을 참조
<list>
리스트나 테이블을 생성
<para>
<summary>, <remarks> 또는 <return> 과 같은 태그 내에서 사용하여 텍스트에 구문 추가
<param>
매개 변수를 설명
<paramref>
특정 단어가 매개변수 임을 나타낸다.
<permission>
멤버 액세스를 문서화 한다.
<remarks>
형식에 대한 정보를 추가하여 <summary> 에 지정한 정보를 보충하는데 사용
<returns>
반환 값을 설명
<see>
텍스트 내부에서 링크를 지정
<seealso>
참고 항목 부분에 나타나는 텍스트를 지정
<summary>
형식 또는 형식 멤버를 설정
<value>
속성을 설명
■ 참조
1. 문서 주석에 대한 권장 태그(C# 프로그래밍 가이드) (MSDN)
2. [C#] 문서화를 자동으로, XML 문서 주석 (ZDNet)
3. Source code documentation generator tool
