【问题标题】：ASP.NET Web API Help Page generates incomplete documentation for F# record typesASP.NET Web API 帮助页面为 F# 记录类型生成不完整的文档
【发布时间】：2014-03-11 17:39:48
【问题描述】：

ASP.NET Web API 帮助页面项目没有为用作 Web API 控制器操作的参数或结果类型的 F# 记录类型生成完整的文档。列出了成员，但 XML cmets 中的摘要信息未显示在生成的文档中。我该如何解决这个问题？

示例

考虑将以下 F# 记录类型用作 Web API 操作方法的参数或结果类型：

[<CLIMutable>]
type ExampleRecord = {

    /// Example property.
    Prop : int

预期输出

为此类型生成的帮助页面文档应在该成员的描述列中包含摘要信息。

名称 │ 描述 │ 类型 │ 附加信息 ══════╪═══════════════════╪═════════╪═════════════ ══════════ 道具│示例属性。 │ 整数 │ 无。

实际输出

我们实际看到的是完全没有摘要信息。

名称 │ 描述 │ 类型 │ 附加信息 ══════╪═════════════╪═════════╪═══════════════════ ════ 道具││整数│无。

细节

此问题与以下特定技术有关：

Microsoft ASP.NET Web API 帮助页面 v5.1.1；
Visual Studio 专业版 2013（更新 1）；和
F# 3.1 编译器。

尽管有自我回答，但对于更好的解决方案来说，地板是敞开的，因为我目前所拥有的并不能真正切芥末。

【问题讨论】：

标签： asp.net-web-api f# visual-studio-2013 asp.net-web-api-helppages

【解决方案1】：

更新：doubled namespace issue has been fixed。未来的读者可能需要调整下面的代码。具体来说，您可能需要将"${namespace}${namespace}${class}" 更改为"${namespace}${class}"。别说我没警告过你！

问题的出现是因为与如何为 F# 记录类型生成 XML 文档相关的两个错误：

“当F#编译器生成文档文件时，它实际上记录的是内部字段而不是记录成员的公共属性。”—Axel Habermaier
生成的 XML 中的namespace of a record member is doubled。

除非更新到 Visual Studio 2013（或者可能只是 F# 编译器），否则最好的解决方法可能是清理生成的 XML 的构建后操作。目前，我有一个临时修复，涉及更改获取成员文档的方法。在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 帮助页面包，它将被覆盖，如果上述错误得到修复，它将破坏一切。非常感谢任何帮助找到更好的解决方案。

【讨论】：