설명서 생성을 위한 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 속성을 설정하더라도 문서 파일이 생성되지 않습니다.

댓글 삽입 단축키 사용

Comments 옵션을 설정하여 C#이나 '''에 ///을 입력한 후 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++)
• 코드 생성