4

The ASP.NET Web API Help Page project does not produce complete documentation for F# record types used as parameters or result types for Web API controller actions. Members are listed, but summary information in XML comments is not displayed in the generated documentation. How do I fix this?

Example

Consider the following F# record type being used as a parameter or result type for a Web API action method:

[<CLIMutable>]
type ExampleRecord = {

    /// Example property.
    Prop : int

Expected output

The generated help page documentation for this type should include the summary information in description column for this member.

Name  │ Description       │ Type    │ Additional information
══════╪═══════════════════╪═════════╪═══════════════════════
Prop  │ Example property. │ integer │ None.

Actual output

What we actually see is that the summary information is completely absent.

Name  │ Description │ Type    │ Additional information
══════╪═════════════╪═════════╪═══════════════════════
Prop  │             │ integer │ None.

Specifics

This issue occurs in relation to the following specific technologies:

  • Microsoft ASP.NET Web API Help Pages v5.1.1;
  • Visual Studio Professional 2013 (Update 1); and
  • F# 3.1 compiler.

Despite the self-answer, the floor is wide open to better solutions as what I've got currently doesn't really cut mustard.

4

1 回答 1

4

更新：双命名空间问题已得到修复。未来的读者可能需要调整下面的代码。具体来说，您可能需要更改"${namespace}${namespace}${class}"为"${namespace}${class}". 别说我没警告过你！

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

  1. “当 F# 编译器生成文档文件时，它实际上记录的是内部字段，而不是记录成员的公共属性。”—<a href="https://stackoverflow.com/a/21302280/230390">Axel Habermaier

  2. 记录成员的命名空间在生成的 XML 中加倍。

除非更新到 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 帮助页面包，它将被覆盖，如果上述错误得到修复，它将破坏事情。我真的很感激任何帮助找到更好的解决方案。

于 2014-03-11T17:39:48.110 回答