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

В классе C# с одним конструктором я могу добавить сводную 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#. Мой вопрос заключается в том, как добавить их в приведенный выше фрагмент кода, чтобы и тип, и конструктор были задокументированы.

4 22
f# xml-documentation

4 ответа:

Я посмотрел на источник открытого компилятора F# и думаю, что Dr_Asik прав-нет способа документировать неявный конструктор с помощью XML - комментария. Узел, представляющий неявный конструктор в 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# со специальными комментариями с помощью Markdown (есть запись в блоге об этом) - так что вы можете рассматривать это как полезное дополнение к стандартному инструменту XML.

15

Точно так же, как и в C#: 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() = ...

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

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

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

Файл.ФС: 

module File

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

Файл.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>
8

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

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

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

3