search

dotnet / fsharp

The F# compiler, F# core library, F# language service, and F# tooling integration for Visual Studio
https://dotnet.microsoft.com/languages/fsharp
MIT License
3.89k stars 783 forks source link

Possible improvements to XML doc processing in the compiler #9805

Open dsyme opened 4 years ago

dsyme commented 4 years ago

The intention for the F# compiler has always been that we would eventually process /// documentation in the same way as the C# compiler but with some additional small features, such as avoiding the need for /// <summary> </summary> tags.

I'm in the process of trialling the use of FSharp.Formatting fsdocs tool on FSharp.Core and noticing some problems with the CML we produce

  1. We don't resolve cref nodes in the compiler. This means F# code has

    /// <exception cref="System.ArgumentNullException">Thrown when the input sequence is null.</exception>
/// <exception cref="System.ArgumentException">Thrown when the input sequence is empty.</exception>

    but the XML produced by C# would include the resolved symbol name e.g. T:System.ArgumentNullException. This means the XML produced by C# is really invalid according the the expected rules for XML doc files in .NET and will cause problems for other .NET tooling (e.g. C# projects looking at FSharp.Core).

I'll add more issues here as I find them

MangelMaxime commented 3 years ago

Hello,

I am looking at improving the TipFormatter from FSAC and came to report this problem.

I think you made a typo:

This means the XML produced by C#

should probably

This means the XML produced by F#