dotnet / dotnet/fsharp

Possible improvements to XML doc processing in the compiler

Open
#9,805 1 comment 2 reactions 0 assignees View on GitHub
Area-XmlDocs Feature Request
Dominant language
F#
Stars
4.3k
Forks
876
Avg merge
4d 11h
Merged PRs (30d)
131

Description

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 `/// ` 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

/// Thrown when the input sequence is null.
/// Thrown when the input sequence is empty.

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.