XML 주석으로 코드 문서화

아티클
12/19/2024

F#의 삼중 슬래시(///) 코드 주석에서 설명서를 생성할 수 있습니다. XML 주석은 코드 파일(.fs) 또는 서명(.fsi) 파일의 선언 앞에 올 수 있습니다.

XML 문서 주석은 사용자 정의 형식 또는 멤버의 정의 위에 추가된 특별한 종류의 주석입니다. 컴파일러에서 처리하여 컴파일 시간에 XML 설명서 파일을 생성할 수 있으므로 특별합니다. IDE가 도구 설명을 사용하여 형식 또는 멤버에 대한 빠른 정보를 표시할 수 있도록 컴파일러에서 생성된 XML 파일을 .NET 어셈블리와 함께 배포할 수 있습니다. 또한 xml 파일은 fsdocs 같은 도구를 통해 실행하여 API 참조 웹 사이트를 생성할 수 있습니다.

기본적으로 XML 문서 주석은 컴파일러에서 무시됩니다. 이를 변경하려면 --warnon:3390설정합니다. 그런 다음 컴파일러는 XML 구문과 <param> 및 <paramref> 태그에 참조된 매개 변수를 확인합니다.

다음 중 하나를 수행하여 컴파일 시간에 XML 파일을 생성할 수 있습니다.

GenerateDocumentationFile 프로젝트 파일의 <PropertyGroup> 섹션에 .fsproj 요소를 추가할 수 있습니다. 그러면 어셈블리와 루트 파일 이름이 같은 XML 파일이 프로젝트 디렉터리에 생성됩니다. 예를 들어:
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
자세한 내용은 GenerateDocumentationFile 속성참조하세요.
Visual Studio를 사용하여 애플리케이션을 개발하는 경우 프로젝트를 마우스 오른쪽 단추로 클릭하고 속성선택합니다. 속성 대화 상자에서 빌드 탭을 선택하고 XML 문서 파일확인하십시오. 컴파일러가 파일을 작성하는 위치를 변경할 수도 있습니다.

XML 설명서 주석을 작성하는 방법에는 XML 태그를 사용 또는 사용하지 않는 두 가지 방법이 있습니다. 둘 다 삼중 슬래시 주석을 사용합니다.

XML 태그가 없는 주석

/// 주석이 <로 시작하지 않으면 전체 주석 텍스트가 바로 다음에 나타나는 코드 구문에 대한 요약 문서로 간주됩니다. 각 구문에 대한 간단한 요약만 작성하려는 경우 이 메서드를 사용합니다.

설명서를 준비하는 동안 주석이 XML 형태로 인코딩되므로, <, >및 & 같은 문자를 굳이 이스케이프할 필요가 없습니다. 요약 태그를 명시적으로 지정하지 않으면, 매개 변수 태그나 반환 태그와 같은 다른 태그도 지정해서는 안 됩니다.

다음 예제에서는 XML 태그 없이 대체 메서드를 보여 줍니다. 이 예제에서는 주석의 전체 텍스트가 요약으로 간주됩니다.

/// Creates a new string whose characters are the result of applying
/// the function mapping to each of the characters of the input string
/// and concatenating the resulting strings.
val collect : (char -> string) -> string -> string

XML 태그가 있는 주석

주석 본문이 <(일반적으로 <summary>)로 시작하는 경우 XML 태그를 사용하여 XML 형식의 주석 본문으로 처리됩니다. 이 두 번째 방법을 사용하면 간단한 요약, 추가 설명, 각 매개 변수 및 형식 매개 변수 및 throw된 예외에 대한 설명서 및 반환 값에 대한 설명을 위해 별도의 메모를 지정할 수 있습니다.

다음은 서명 파일의 일반적인 XML 설명서 주석입니다.

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string and concatenating the resulting
/// strings.</summary>
/// <param name="mapping">The function to produce a string from each character of the input string.</param>
///<param name="str">The input string.</param>
///<returns>The concatenated string.</returns>
///<exception cref="System.ArgumentNullException">Thrown when the input string is null.</exception>
val collect : (char -> string) -> string -> string

권장 태그

XML 태그를 사용하는 경우 다음 표에서는 F# XML 코드 주석에서 인식되는 외부 태그에 대해 설명합니다.

태그 구문	묘사
텍스트	텍스트 프로그램 요소에 대한 간략한 설명이 되도록 지정합니다. 설명은 일반적으로 하나 또는 두 개의 문장입니다.
텍스트	텍스트 프로그램 요소에 대한 추가 정보가 포함되도록 지정합니다.
`<param name="` 이름`">`설명`</param>`	함수 또는 메서드 매개 변수의 이름과 설명을 지정합니다.
`<typeparam name="` 이름`">`설명`</typeparam>`	형식 매개 변수의 이름과 설명을 지정합니다.
텍스트	텍스트 함수 또는 메서드의 반환 값을 설명함을 지정합니다.
`<exception cref="` 형식`">`설명`</exception>`	생성할 수 있는 예외 유형과 예외가 throw되는 상황을 지정합니다.
`<seealso cref="` 참조`"/>`	다른 타입의 설명서에 대한 참조 링크를 지정합니다. 참조 XML 설명서 파일에 표시되는 이름입니다. 참고 링크는 일반적으로 설명서 페이지의 맨 아래에 표시됩니다.

다음 표에서는 설명 섹션 내에서 사용할 태그에 대해 설명합니다.

태그 구문	묘사
텍스트	텍스트 단락을 지정합니다. 주석 태그 내 텍스트를 분리하는 데 사용됩니다.
텍스트	텍스트은 여러 줄의 코드로 명시합니다. 이 태그는 문서 생성기에서 코드에 적합한 글꼴로 텍스트를 표시하는 데 사용할 수 있습니다.
`<paramref name="` 이름`"/>`	동일한 설명서 주석의 매개 변수에 대한 참조를 지정합니다.
`<typeparamref name="` 이름`"/>`	동일한 설명서 주석의 형식 매개 변수에 대한 참조를 지정합니다.
텍스트	텍스트 인라인 코드임을 지정합니다. 이 태그는 문서 생성기에서 코드에 적합한 글꼴로 텍스트를 표시하는 데 사용할 수 있습니다.
`<see cref="` 참조`">`*텍스트*`</see>`	다른 프로그램 요소에 대한 인라인 링크를 지정합니다. 참조 XML 설명서 파일에 표시되는 이름입니다. 텍스트은 링크에 표시된 텍스트입니다.

사용자 정의 태그

이전 태그는 F# 컴파일러 및 일반적인 F# 편집기 도구에서 인식되는 태그를 나타냅니다. 그러나 사용자는 자신의 태그를 자유롭게 정의할 수 있습니다. fsdocs와 같은 도구는 <namespacedoc>같은 추가 태그를 지원합니다. 사용자 지정 또는 사내 설명서 생성 도구는 표준 태그와 함께 사용할 수 있으며 HTML에서 PDF로의 여러 출력 형식을 지원합니다.

컴파일 시간 검사

--warnon:3390 사용하도록 설정하면 컴파일러는 XML 구문과 <param> 및 <paramref> 태그에 참조된 매개 변수를 확인합니다.

F# 구조 문서화

모듈, 멤버, 공용 구조체 사례 및 레코드 필드와 같은 F# 구문은 선언 직전에 /// 주석으로 문서화됩니다. 필요한 경우 인수 목록 앞에 /// 주석을 제공하여 클래스의 암시적 생성자를 문서화합니다. 예를 들어:

/// This is the type
type SomeType
      /// This is the implicit constructor
      (a: int, b: int) =

    /// This is the member
    member _.Sum() = a + b

제한사항

C# 및 기타 .NET 언어의 XML 설명서의 일부 기능은 F#에서 지원되지 않습니다.

F#에서 상호 참조는 해당 기호의 전체 XML 서명(예: cref="T:System.Console")을 사용해야 합니다. cref="Console" 같은 간단한 C#스타일 상호 참조는 전체 XML 서명에 대해 자세히 설명하지 않으며 F# 컴파일러에서 이러한 요소를 확인하지 않습니다. 일부 설명서 도구를 사용하면 후속 처리에서 이러한 상호 참조를 사용할 수 있지만 전체 서명을 사용해야 합니다.
<include> <inheritdoc>태그는 F# 컴파일러에서 지원되지 않습니다. 사용하는 경우 오류가 발생하지 않지만 생성된 설명서에 영향을 주지 않고 생성된 설명서 파일로 복사됩니다.
-warnon:3390 사용되는 경우에도 F# 컴파일러에서 상호 참조를 확인하지 않습니다.
태그 <typeparam> 및 <typeparamref>의 이름은 --warnon:3390가 사용될 때에도 F# 컴파일러에서 확인되지 않습니다.
설명서가 누락된 경우 --warnon:3390 사용되는 경우에도 경고가 표시되지 않습니다.

권장 사항

코드 문서화는 여러 가지 이유로 권장됩니다. 다음은 몇 가지 모범 사례, 일반 사용 사례 시나리오 및 F# 코드에서 XML 설명서 태그를 사용할 때 알아야 할 사항입니다.

코드에서 --warnon:3390 옵션을 사용하도록 설정하여 XML 설명서가 유효한 XML인지 확인합니다.
긴 XML 설명서 주석을 구현과 구분하기 위해 서명 파일을 추가하는 것이 좋습니다.
일관성을 위해 공개적으로 표시되는 모든 형식과 해당 멤버를 문서화해야 합니다. 꼭 해야 한다면, 모두 하세요.
최소한 모듈, 형식 및 해당 멤버에는 일반 /// 주석 또는 <summary> 태그가 있어야 합니다. F# 편집 도구의 자동 완성 도구 설명 창에 표시됩니다.
문서 텍스트는 완전한 문장으로 마침표를 사용하여 작성해야 합니다.

다음을 통해 공유