XML 문서(F#)
F#에서 삼중 슬래시(///) 코드 주석을 통해 문서를 생성할 수 있습니다. XML 주석은 코드 파일(.fs)이나 시그니처 파일(.fsi)에서 선언 앞에 올 수 있습니다.
주석에서 문서 생성
주석에서 문서를 생성하기 위한 F#의 지원 기능은 다른 .NET Framework 언어의 경우와 같습니다. 다른 .NET Framework 언어와 마찬가지로 -doc 컴파일러 옵션을 사용하여 문서로 변환 가능한 정보가 들어 있는 XML 파일을 만들 수 있습니다. 정보를 문서로 변환하는 데는 Sandcastle 같은 도구를 사용할 수 있습니다. 다른 .NET Framework 언어로 작성된 어셈블리에 사용하기 위해 디자인된 도구로 생성한 문서에는 일반적으로 컴파일된 형식의 F# 구문을 기반으로 하는 API가 표시됩니다. 특별히 F#을 지원하는 도구가 아니라면 이러한 도구를 사용하여 생성된 문서가 F#의 API 보기에 일치하지 않습니다.
XML로부터 문서를 생성하는 방법에 대한 자세한 내용은 XML 문서 주석(C# 프로그래밍 가이드)을 참조하십시오.
권장 태그
XML 문서 주석을 작성하는 데는 두 가지 방법이 있습니다. 그중 하나는 XML 태그를 사용하지 않고 삼중 슬래시 주석에 직접 문서를 작성하는 방법입니다. 이 방법을 사용하면 전체 주석 텍스트가 바로 뒤에 나오는 코드 구문에 대한 요약 문서로 사용됩니다. 이 방법은 각 구문에 대한 간단한 요약만 작성하려는 경우에 유용합니다. 다른 방법은 XML 태그를 사용하여 구조적으로 더 체계화된 문서를 제공하는 것입니다. 이 둘째 방법을 사용하면 간단한 요약, 추가 설명, 각 매개 변수, 형식 매개 변수 및 throw된 예외에 대한 설명, 반환 값에 대한 설명 등에 대해 개별 메모를 지정할 수 있습니다. 다음 표에는 F# XML 코드 주석에 사용할 수 있는 XML 태그에 대한 설명이 나와 있습니다.
태그 구문 |
설명 |
|---|---|
<c> text </c> |
text가 코드임을 나타냅니다. 문서 생성기에서 코드에 적합한 글꼴로 텍스트를 표시하는 데 이 태그를 사용할 수 있습니다. |
<summary> text </summary> |
text가 프로그램 요소에 대한 간단한 설명임을 나타냅니다. 설명은 대부분 한두 문장으로 이루어집니다. |
<remarks> text </remarks> |
text가 프로그램 요소에 대한 보충 정보임을 나타냅니다. |
<param name="name"> description </param> |
함수 또는 메서드 매개 변수에 대한 이름과 설명을 지정합니다. |
<typeparam name="name"> description </typeparam> |
형식 매개 변수에 대한 이름과 설명을 지정합니다. |
<returns> text </returns> |
text가 함수 또는 메서드의 반환 값에 대한 설명임을 나타냅니다. |
<exception cref="type"> description </exception> |
생성될 수 있는 예외의 형식 및 예외가 throw되는 조건을 지정합니다. |
<see cref="reference"> text </see> |
다른 프로그램 요소에 대한 인라인 링크를 지정합니다. reference는 XML 문서 파일에 표시되는 이름입니다. text는 링크에 표시되는 텍스트입니다. |
<seealso cref="reference"/> |
다른 형식에 대한 문서로 연결되는 참고 항목 링크를 지정합니다. reference는 XML 문서 파일에 표시되는 이름입니다. 참고 항목 링크는 일반적으로 문서 페이지 아래쪽에 표시됩니다. |
<para> text </para> |
텍스트의 단락을 지정합니다. 이는 remarks 태그 내의 텍스트를 구분하는 데 사용됩니다. |
예제
설명
다음은 시그니처 파일의 일반적인 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 태그를 사용하지 않은 대체 방법을 보여 줍니다. 이 예제에서는 주석의 텍스트 전체가 요약으로 간주됩니다. summary 태그를 명시적으로 지정하지 않은 경우에는 param, returns 등과 같은 다른 태그도 지정하지 말아야 합니다.
코드
/// 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