4

ASP.NET Web API ヘルプ ページ プロジェクトでは、Web API コントローラー アクションのパラメーターまたは結果の型として使用される F# レコード型の完全なドキュメントは作成されていません。メンバーはリストされますが、XML コメント内の要約情報は生成されたドキュメントには表示されません。これを修正するにはどうすればよいですか?

例

次の F# レコード タイプが、Web API アクション メソッドのパラメーターまたは結果タイプとして使用されているとします。

[<CLIMutable>]
type ExampleRecord = {

    /// Example property.
    Prop : int

期待される出力

このタイプの生成されたヘルプ ページ ドキュメントには、このメンバーの説明列に概要情報が含まれている必要があります。

名前 │ 説明 │ タイプ │ 追加情報
══════╪═══════════════════╪═════════╪═════════════ ══════════
Prop │ プロパティの例。│ 整数 │ なし。

実際の出力

実際に見られるのは、要約情報がまったくないことです。

名前 │ 説明 │ タイプ │ 追加情報
══════╪═════════════╪═════════╪═══════════════════ ════
Prop │ │ 整数 │ なし。

仕様

この問題は、次の特定のテクノロジに関連して発生します。

  • Microsoft ASP.NET Web API ヘルプ ページ v5.1.1;
  • Visual Studio Professional 2013 (アップデート 1); と
  • F# 3.1 コンパイラ。

自己回答にもかかわらず、私が現在持っているものは実際にはマスタードをカットしていないため、フロアはより良い解決策に対して広く開かれています.

4

1 に答える 1

4

更新:二重化された名前空間の問題が修正されました。将来の読者は、以下のコードを調整する必要があるかもしれません。"${namespace}${namespace}${class}"具体的には、に変更する必要がある場合があります"${namespace}${class}"。警告しなかったなんて言わないで！

この問題は、F# レコード型の XML ドキュメントの生成方法に関連する 2 つのバグが原因で発生します。

  1. 「F# コンパイラがドキュメント ファイルを生成するとき、実際には、レコード メンバーのパブリック プロパティではなく、内部フィールドをドキュメント化します。」—<a href="https://stackoverflow.com/a/21302280/230390">Axel Habermaier

  2. レコード メンバーの名前空間は、生成された XML で 2 倍になります。

Visual Studio 2013 (またはおそらく F# コンパイラー) への更新がない限り、これに対する最善の修正は、生成された XML をクリーンアップするビルド後のアクションでしょう。今のところ、members.In のドキュメントを取得するメソッドを変更することを含む一時的な修正がありAreas/HelpPage/XmlDocumentationProvider、シグネチャを持つメソッドを見つけます。

public string GetDocumentation(MemberInfo member)

…定義を次のように置き換えます。

public string GetDocumentation(MemberInfo member)
{
    string selectExpression;
    bool isRecord = FSharpType.IsRecord(member.DeclaringType, FSharpOption<BindingFlags>.None);

    if (isRecord)
    {
        // Workaround for a bug in VS 2013.1: duplicated namespace in documentation for record types.
        Regex matchTypeName = new Regex(@"(?<namespace>(?:[_\p{L}\p{Nl}]+\.)*)(?<class>[_\p{L}\p{Nl}]+)$");
        string classExpression = matchTypeName.Replace(GetTypeName(member.DeclaringType), "${namespace}${namespace}${class}");
        string memberExpression = String.Format(CultureInfo.InvariantCulture, "{0}.{1}", classExpression, member.Name);
        selectExpression = String.Format(CultureInfo.InvariantCulture, FieldExpression, memberExpression);
    }
    else
    {
        string expression = member.MemberType == MemberTypes.Field ? FieldExpression : PropertyExpression;
        string memberName = String.Format(CultureInfo.InvariantCulture, "{0}.{1}", GetTypeName(member.DeclaringType), member.Name);
        selectExpression = String.Format(CultureInfo.InvariantCulture, expression, memberName);
    }

    XPathNavigator propertyNode = _documentNavigator.SelectSingleNode(selectExpression);
    return GetTagValue(propertyNode, "summary");
}

これは非常に一時的な修正です。Web API ヘルプ ページ パッケージを更新すると上書きされ、前述のバグが修正されると問題が発生します。より良い解決策を見つける手助けをしていただければ幸いです。

于 2014-03-11T17:39:48.110 に答える