라이브러리 xml 문서 생성 (API Documentation)

Visual Studio에는 실행을 하기위한 Application이 아닌 Class Library로 프로젝트를 빌드를 했을 때 유용한 기능이 있다.

(C# 뿐만 아니라 다른 언어에 대해서도 지원한다.)

 

라이브러리 프로젝트에 담긴 형식에 맞는 주석(xml 형식)을 빌드한 라이브러리 파일을 가져다 사용하는 프로젝트에서도 동일하게 확인할 수 있다.

---

 

사용자 정의 주석

위 이미지는 라이브러리 프로젝트에서의 코드이다. summary를 작성하고 마우스를 클래스에 올려다 두면 해당 설명이 표시가 된다! 

(흔히 코드를 작성할 때, 미리 컴파일되어 있는 파일에 있는 프로퍼티나 함수에 대한 설명이 나오는 것이 바로 이런 것이다.)

 

위와 같은 기능을 컴파일된 라이브러리를 사용하는 다른 프로젝트에서도 동일하게 사용할 수 있다!

---

먼저 간단하게 주석을 작성하는 방법에 대해서 알아보자.

 

매우 간단한 방법이 존재한다. 

클래스나, 프로퍼티(속성), 변수, 메서드의 선언 위에서 `/// (/ 3번)`을 입력하면 자동으로 포맷이 생성된다.

(namespace에 대해서는 주석이 제공되지 않는다.)

 

아래 이미지는 클래스, 변수, 메서드 윗 라인에서 `///`을 입력했을 때 자동으로 완성된 포맷이다.

 

 

특히 메서드 부분을 자세히 들여다 보면 아래와 같다.

메서드의 경우, summary 뿐만 아니라, 파라미터의 이름과 설명, 그리고 반환 값이 있는 경우 반환값에 대한 설명까지 작성할 수 있는 포맷이 나타난다.

 

물론 형식에 맞게 더 다양한 태그들을 이용하여 작성할 수도 있다.

예를 들어 줄바꿈은 <br/>을 넣어서 표현할 수 있다.

 

좀 더 자세한 정보는 아래를 참조하자.

https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags

Recommended XML documentation tags for a class and its members - C#

---

프로젝트 설정에서 Documentation 생성 설정을 한다.

 

다음 과정을 통해 빌드 시 Documentation을 생성하도록 할 수 있다.

1. 프로젝트 선택

2. 우클릭 -> Properties

3. Build -> Ouput

4. Documentation file에서 Generate a file containing API documentation 체크

5. (필요한 경우) Xml documentation file path 지정 (default는 빌드 경로와 동일하다.)

 

*** 물론, 프로젝트 속성 파일을 다음과 같이 직접 작성해도 무방하다.

파일: [ProjectName].csproj

...

<PropertyGroup>
	...
    <GenerateDocumentationFile>True</GenerateDocumentationFile>
    <DocumentationFile>$(SolutionDir)\[경로 및 대상 파일]</DocumentationFile>
...

 

 

이후 프로젝트 빌드에 성공하면 xml document 파일이 생성될 것이다.

---

프로젝트에 빌드된 라이브러리 추가

 

1. 프로젝트 선택

2. 우클릭 -> Add

3. (VS 버전에 따라 다를 수 있지만,) Reference ...가 있는 메뉴 선택

4. Browse -> Browse... 에서 라이브러리 파일 선택 후 OK

5. 라이브러리 파일과 xml 파일이 같은 경로에 있으면 된다.

 

 

이후 프로젝트에서 다음과 같이 라이브러리 프로젝트에서와 같은 주석을 확인할 수 있다.

 

 

만약 바로 나타나지 않는다면 다시 추가해보거나 Visual Studio를 다시 시작해보자.

---

참고로, Documentation 파일을 생성할 경우, 주석 내용이 없는 함수나 클래스 등에 대해서 Warning: CS1591이 나타날 수 있는데, 무시하고 싶으면 프로젝트 속성에서 Errors and warnings 항목의 Suppress specific warnings에 해당 값(1591)을 추가해 주면 될 것이다.