XML 주석을 사용하여 코드 문서화
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# 편집 도구의 자동 완성 도구 설명 창에 표시됩니다.문서 텍스트는 마침표로 끝나는 전체 문장을 사용하여 기록되어야 합니다.
참고 항목
.NET