Документирование кода F #

В классе С# с единственным конструктором я могу добавить XML-документацию по XML и документацию конструктора XML:

///<summary>
///This class will solve all your problems
///</summary>
public class Awesome
{
    /// <summary>
    /// Initializes a new instance of the <see cref="Awesome"/> class.
    /// </summary>
    /// <param name="sauce">The secret sauce.</param>       
    public Awesome(string sauce)
    {
        //...implementation elided for security purposes
    }
}

Как мне сделать то же самое с эквивалентным классом F #, чтобы сгенерированная документация была одинаковой?

type Awesome(sauce: string) = 
    //...implementation elided for security purposes

ПОДТВЕРЖДЕНИЕ: Я знаю, что стандартные теги документации XML могут использоваться в F #. Мой вопрос заключается в том, как добавить их к приведенному выше фрагменту, чтобы документировать как тип, так и конструктор.

Ответы

Ответ 1

Я посмотрел источник компилятора F # с открытым исходным кодом, и я думаю, что Dr_Asik прав - нет способа документировать неявный конструктор с комментарием XML. node, который представляет неявный конструктор в AST (см. ImplicitCtor в ast.fs здесь), не содержит поля для обработки документации XML (представленной как PreXmlDoc).

Вы все еще можете документировать весь открытый API - вам нужно будет использовать метод, описанный Dr_Asik, и пометить неявный конструктор как private. Я согласен, что это немного уродливо, но я думаю, что это более удобно, чем использование неявных конструкторов:

type MyType private(a:int, u:unit) =
  /// <summary>Creates MyType</summary>
  /// <param name="a">Parameter A</param>
  new(a:int) = MyType(a, ())

Я добавил фиктивный параметр u в неявный конструктор, чтобы его можно было вызвать из публичного конструктора. Во всяком случае, я думаю, что это следует рассматривать как ошибку языка, поэтому я предлагаю сообщить об этом fsbugs в microsoft dot com.

Как и в стороне, я думаю, что XML-документация в основном полезна как источник данных для IntelliSense (которая все еще нуждается в документации для конструктора), и я создал несколько альтернативных инструментов F #, которые позволяют создавать учебные пособия и документацию, F # script со специальными комментариями с помощью Markdown (есть сообщение в блоге об этом) - так что вы можете считать это полезным дополнением к стандартным инструментам XML.

Ответ 2

Точно так же, как в С#: http://msdn.microsoft.com/en-us/library/dd233217.aspx

Если вы не ставите теги, F # предполагает, что это "summary":

/// This is the documentation
type MyType() = ....

... эквивалентно

/// <summary>This is the documentation</summary>
type MyType() = ...

Если вы хотите документировать конструктор, вам придется объявить его явно. AFAIK нет способа документировать основной конструктор.

/// [Type summary goes here]
type MyType(a : int) =
    let m_a = a
    /// [Parameterless constructor documentation here]
    new() = MyType(0)

Ответ 3

Невозможно документировать неявный конструктор с комментарием XML в исходном файле F # (.fs). Один из способов - явно объявить конструктор (см. Ответ д-ра Асика). Другой - помещать ваши комментарии XML в файл подписи F # (.fsi).

File.fs:

module File

type Awesome(sauce: string) =
    member x.Sauce = sauce

File.fsi

module File

type Awesome =
  class
    /// Implicit constructor summary for the Awesome type
    new : sauce:string -> Awesome
    member Sauce : string
  end

Документация XML для этой сборки теперь будет содержать правильное резюме:

<member name="M:File.Awesome.#ctor(System.String)">
<summary>
 Implicit constructor summary for the Awesome type
</summary>
</member>

Ответ 4

Это действительно раздражающая проблема. Другое решение, которое я использовал, заключается в том, чтобы не полагаться на первичный конструктор:

/// Documentation type.
type Awesome =
    val sauce : string
    /// <summary>Documentation constructor.</summary>
    /// <param name="sauce">Sauce. Lots of it.</param>
    new (sauce) = { sauce = sauce }

Более подробные, но не нужны дополнительные файлы или частные конструкторы...