XML documentation for interface methods and record properties

问题

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

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:

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:
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? :)

[EDIT]

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

Unfortunately same docs are not visible in C#:

回答1:

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

is equivalent to this:

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

1) Descriptions for record fields work in VS2012:

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

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

回答2:

As noted by Patryk Ćwiek in the comment above, Microsoft has confirmed this as a bug. Just to clarify what actually happens: When the F# compiler generates the documentation file, it actually documents the internal field instead of the public property of the record member.

For instance, the documentation for your Summary type above is generated as:

...
<member name="F:Test.Summary.IsSuccessful">
   <summary>Gets whether the action was successful or not</summary>
</member>
<member name="F:Test.Summary.Name">
   <summary>Gets a short name</summary>
</member>
<member name="T:Test.Summary">
   <summary>Well, it's a summary</summary>
</member>
...

Note the F: prefix in the documentation of the member names. Change that to P: and Visual Studio immediately displays the comments in your C# project. So until this bug is fixed and the documentation is actually generated for the properties, the only option you have is to manually process the documentation file in a post-build step.

By the way, this also explains why it works in F#: Apparently, the F# bindings for Visual Studio use the field to look up the documentation. This even works across several F# libraries, despite the fact that the field has internal visibility.

Update: This bug should be fixed with F# 3.1.2. See also the release notes.

来源：https://stackoverflow.com/questions/20016568/xml-documentation-for-interface-methods-and-record-properties

标签

intellisense

c#-to-f#