문서 생성에 대한 XML 주석 삽입

이 문서에서는 Visual Studio가 표준 XML 문서 주석 구조를 자동으로 생성하여 클래스와 메서드 같은 코드 요소를 문서화하는 데 어떻게 도움이 되는지 설명합니다. 컴파일 타임에 문서 주석이 포함된 XMl 파일을 생성할 수 있습니다.

Visual Studio 및 기타 IDE가 IntelliSense를 사용하여 형식 및 멤버에 대한 빠른 정보를 표시할 수 있도록 컴파일러에서 생성된 XML 파일은 .NET 어셈블리와 함께 배포될 수 있습니다. 또한 DocFX 및 Sandcastle 같은 도구를 통해 XML 파일을 실행하여 API 참조 웹사이트를 생성할 수 있습니다.

참고 항목

XML 문서 주석 구조를 자동으로 삽입하는 주석 삽입 명령은 C# 및 Visual Basic에서 사용할 수 있습니다. C++의 경우 XML 문서 주석을 수동으로 삽입하고 컴파일 타임에도 XML 문서 파일을 생성할 수 있습니다.

문서 생성 사용

문서 생성을 사용하려면 프로젝트 속성의 빌드>출력 탭에서 API 문서가 포함된 파일 생성 확인란을 선택합니다.

기본적으로 .xml 파일 확장자를 가진 어셈블리와 동일한 이름의 문서 파일은 어셈블리와 동일한 디렉터리에 생성됩니다. 파일의 기본값이 아닌 이름이나 위치를 구성하려면 XML 문서 파일 경로에서의 대체 위치를 입력하거나 찾습니다.

또는 GenerateDocumentationFile 또는 DocumentationFile 속성을 .csproj, .vbproj 또는 .fsproj 파일에 추가할 수 있습니다. GenerateDocumentationFile을(를) true(으)로 설정하면 기본 이름과 위치로 문서 파일이 생성됩니다. DocumentationFile 속성을 사용하여 다른 이름 또는 위치를 지정합니다.

DocumentationFile을(를) 단독으로 사용하거나 GenerateDocumentationFile 속성을 true(으)로 설정하여 사용하는 경우 지정된 이름과 위치가 있는 문서 파일이 생성됩니다. 그러나 GenerateDocumentationFile을(를) false(으)로 설정하면 DocumentationFile 속성을 설정하더라도 문서 파일이 생성되지 않습니다.

메모 삽입 바로 가기 키 사용

C#에서는 /// 또는 Visual Basic에서는 '''을(를) 입력한 후 XML 주석 구조를 자동으로 삽입하도록 메모 옵션을 설정할 수 있습니다.

1. Visual Studio 메뉴 모음에서 도구>옵션을 차례로 선택합니다.
2. 옵션 대화 상자에서 텍스트 편집기>C#(또는 Visual Basic) >고급으로 이동합니다.
3. 메모 섹션에서 \\\(또는 ''')에 대한 XML 문서 주석 생성을 선택하거나 선택 취소합니다.

XML 주석 자동 삽입

1. Visual Studio에서 문서화할 요소(예: 메서드) 위에 커서를 놓습니다.

2. 다음 작업 중 하나를 수행합니다.

   • 자동 주석 삽입 바로 가기를 사용하는 경우 C#에서는 ///, Visual Basic에서는 '''을(를) 입력합니다.
   • 편집 메뉴에서 IntelliSense>주석 삽입을 선택합니다.
   • 마우스 오른쪽 단추 클릭 또는 컨텍스트 메뉴에서 코드 조각>주석 삽입을 선택합니다.

   XML 주석 구조는 코드 요소 위에 즉시 생성됩니다. 예를 들어 다음 GetUserName 메서드에 주석을 달 때 템플릿은 <summary> 요소, 각 매개 변수의 <param> 요소 및 반환 값을 문서화하기 위한 <returns> 요소를 생성합니다.

   /// <summary>
   /// 
   /// </summary>
   /// <param name="id"></param>
   /// <returns></returns>
   public string GetUserName(int id)
   {
       return "username";
   }
   

   ''' <summary>
   ''' 
   ''' </summary>
   ''' <param name="id"></param>
   ''' <returns></returns>
   Public Function GetUserName(id As Integer) As String
       Return "username"
   End Function
   

3. 각 XML 요소에 대한 설명을 입력하여 코드를 완전히 문서화합니다. 예시:

    /// <summary>
    /// Gets the username associated with the specified ID.
    /// </summary>
    /// <param name="id">The unique user ID.</param>
    /// <returns>A string containing the username for the specified ID.</returns>
    public string GetUserName(int id)
    {
        return "username";
    }
   

코드 위로 마우스로 가져가면 요약 정보로 렌더링되는 주석에 XML 요소와 스타일을 사용할 수 있습니다. 이러한 요소에는 기울임꼴 또는 굵은 스타일, 글머리 기호 또는 번호 매기기 목록, 클릭 가능한 cref 또는 href 링크가 포함됩니다.

예를 들어 C# 프로그램 파일에 다음 코드를 입력합니다.

/// <summary>
/// There are two <see href="https://bing.com">params</see>.
/// <list type="number">
/// <item><param name="id">The user <em>id</em></param></item>
/// <item><param name="username">The user <em>name</em></param></item>
/// </list>
/// </summary>
/// <returns>The <strong>username</strong>.</returns>
public static string GetUserName(int id)
{
    return "username";
}

GetUserName 위로 마우스를 가져가면 빠른 정보 창이 다음과 같이 표시됩니다.

관련 콘텐츠

• 문서 주석
• Visual Basic의 XML 문서
• 주석(C++)
• XML 문서(Visual C++)
• 코드 생성