XML 주석을 사용하여 코드 문서화

아티클
03/05/2024

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

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

아래 설명된 옵션을 사용하여 컴파일 시간에 주석의 유효성과 완전성을 검사 않는 한 다른 모든 주석과 마찬가지로 XML 문서 주석은 컴파일러에서 무시됩니다.

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

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

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

XML 태그가 없는 주석

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

설명서를 준비하는 동안 주석이 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 코드 주석에서 인식되는 외부 태그에 대해 설명합니다.

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

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

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

사용자 정의 태그

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

컴파일 시간 검사

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

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". 전체 XML 서명에 대해 자세히 설명하지 않고 이러한 요소와 같은 cref="Console" 간단한 C#스타일의 상호 참조는 F# 컴파일러에서 검사 않습니다. 일부 설명서 도구를 사용하면 후속 처리에서 이러한 상호 참조를 사용할 수 있지만 전체 서명을 사용해야 합니다.
태그는 <include><inheritdoc> F# 컴파일러에서 지원되지 않습니다. 사용하는 경우 오류가 발생하지 않지만 생성된 설명서에 영향을 주지 않고 생성된 설명서 파일로 복사됩니다.
상호 참조는 사용되는 경우에도 -warnon:3390 F# 컴파일러에서 검사 않습니다.
태그 <typeparam><typeparamref> 에 사용되는 이름은 F# 컴파일러 --warnon:3390 에서 검사 않습니다.
설명서가 누락된 경우 사용되는 경우에도 --warnon:3390 경고가 제공되지 않습니다.

권장 사항

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

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