接口方法和记录属性的XML文档 [英] XML documentation for interface methods and record properties

问题描述

似乎XML文档在大多数情况下都能正常工作，但并非总是如此。我想使Intellisense对于设计用于与C＃互操作的部件完全可用。因此，这是一个小示例（也许有些人为设计）：

It seems the XML documentation works fine for the most cases, but not always. I wanted to make the Intellisense fully available for the parts that are designed for interoperating with C#. So, here's a small (and maybe a bit contrived) example:

///<summary>Well, it's a summary</summary>
type Summary = {
    ///<summary>Gets a short name</summary>
    Name : string;

    ///<summary>Gets whether the action was successful or not</summary>
    IsSuccessful : bool;
}

///<summary>Represents path filtering action</summary>
type IPathFilter =
    ///<summary>Runs the filtering through the list of <paramref name="paths"/></summary>
    ///<param name="paths">A sequence of paths to check</param>
    ///<returns>A sequence of <see cref="Summary"/></returns>
    abstract member Run : seq<string> -> seq<Summary>

///<summary>A default filter</summary>
type PathFilter =

    ///<summary>Runs the filtering through the list of <paramref name="paths"/></summary>
    ///<param name="paths">A sequence of paths to check</param>
    ///<returns>A sequence of <see cref="Summary"/></returns>
    member this.Run paths=
        paths |> Seq.map (fun s -> FileInfo(s)) |> Seq.map (fun f -> { Name = f.Name; IsSuccessful = f.Exists; })

    interface IPathFilter with
        ///<summary>Runs the filtering through the list of <paramref name="paths"/></summary>
        ///<param name="paths">A sequence of paths to check</param>
        ///<returns>A sequence of <see cref="Summary"/></returns>
        member this.Run paths = 
            this.Run paths

类和该接口仅适用于C＃互操作，这是F＃库中发生的所有不可思议的事物的外观，因此我不必将F＃特定的事物暴露给C＃。在C＃端有完整的文档很高兴，这使我想到了两个问题：

The class and the interface are there only for C# interop, a facade for all the magic stuff that happens inside F# library, so I don't have to expose the F# specific stuff to C#. It would be nice to have full docs available on C# side, which brings me to my two questions:

1. 有没有办法在Intellisense中记录记录属性并使其可见？如果我将鼠标悬停在类型本身上，则所有内容都可以使用，但是属性似乎没有被使用：
   
   

1. Is there a way to have the record properties documented and visible in Intellisense? If I hover over the type itself everything works, but properties don't seem to be picked up:

是否可以对抽象方法进行完整描述？我知道，从F＃角度来看，它们仅被描述为函数签名。不幸的是，这意味着如果我正在使用该界面，则该方法将获得不完整的文档。参数名称和描述将丢失：

Is there a way to have a 'full' description for abstract methods? I know, from F# side they're only described as a function signature. Unfortunately, that means if I'm using the interface, I'll get incomplete docs on the method; the parameter names and descriptions will be missing:

与原始类文档相比：

Compared to the raw class documentation:

我有什么可以做的，还是应该学习与他人共处？它？ ：）

Is there anything I can do, or should I just learn to live with it? :)

如古斯塔沃所说，记录文档似乎在F＃端工作正常（使用VS2012 Professional检查）：

As noted by Gustavo, record docs seem to work just fine on F# side (checked using VS2012 Professional):

很遗憾，在C＃中看不到相同的文档：

Unfortunately same docs are not visible in C#:

：（

推荐答案

请注意，您可以省略摘要标签，当您没有 params 和 returns 之类的其他标签时。

Note that you can omit the summary tag when you don't have other tags like params and returns. So this:

///Well, it's a summary
type Summary

等效于此：

///<summary>Well, it's a summary</summary>
type Summary

1）记录字段的说明在VS2012中有效：

1) Descriptions for record fields work in VS2012:

2）您可以在抽象方法中使用参数名称，例如：

2) You can use parameter names in abstract methods like this:

type IPathFilter =
    abstract member Run : paths:seq<string> -> seq<Summary>

这篇关于接口方法和记录属性的XML文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！