Summary
fsdocs (23.0.0-alpha.1) fails to read the XML comments of type abbreviations whose target is a tuple, a list or string, logging Could not read comments from entity ... The entity System.Tuple2 was not registered before!`. The comments on those abbreviations are then dropped from the generated API docs.
Repro
Building the API docs for FSharp.Compiler.Service from https://github.com/dotnet/fsharp gives 20 of these. The abbreviation and the type that the resolver stumbles on:
FSharp.Compiler.AbstractIL.IL.ILAttributeNamedArg <- System.Tuple`4
FSharp.Compiler.AbstractIL.IL.ILGenericArgs <- Microsoft.FSharp.Collections.FSharpList`1
FSharp.Compiler.AbstractIL.IL.ILParameters <- Microsoft.FSharp.Collections.FSharpList`1
FSharp.Compiler.AbstractIL.ILBinaryReader.ILReaderMetadataSnapshot <- System.Tuple`3
FSharp.Compiler.CodeAnalysis.FileName <- System.String
FSharp.Compiler.EditorServices.CompletionPath <- System.Tuple`2
FSharp.Compiler.Syntax.LongIdent <- Microsoft.FSharp.Collections.FSharpList`1
FSharp.Compiler.Syntax.SynAttributes <- Microsoft.FSharp.Collections.FSharpList`1
FSharp.Compiler.Text.Position01 <- System.Tuple`2
FSharp.Compiler.Text.Range01 <- System.Tuple`2
Minimal equivalents:
/// A position as a zero-based line and column
type Position01 = int * int
/// A long identifier
type LongIdent = Ident list
/// A file name
type FileName = string
Stack trace:
warning: Could not read comments from entity 'FSharp.Compiler.AbstractIL.IL.ILAttributeNamedArg': System.Exception: The entity System.Tuple`4 was not registered before!
at Microsoft.FSharp.Core.PrintfModule.PrintFormatToStringThenFail@1447.Invoke(String message)
at FSharp.Formatting.ApiDocs.CrossReferenceResolver.mfvToCref(FSharpMemberOrFunctionOrValue mfv) in src/FSharp.Formatting.ApiDocs/CrossReferenceResolver.fs:line 476
at FSharp.Formatting.ApiDocs.CrossReferenceResolver.tryResolveCrossReferenceForMemberByXmlSig(String memberXmlSig) in src/FSharp.Formatting.ApiDocs/CrossReferenceResolver.fs:line 494
at FSharp.Formatting.ApiDocs.CrossReferenceResolver.ResolveCref(String cref) in src/FSharp.Formatting.ApiDocs/CrossReferenceResolver.fs:line 633
at FSharp.Formatting.ApiDocs.CrossReferenceResolver.IsLocal(String cref) in src/FSharp.Formatting.ApiDocs/CrossReferenceResolver.fs:line 662
at FSharp.Formatting.ApiDocs.SymbolReader.readCommentAndCommands(ReadingContext ctx, String xmlSig, FSharpOption`1 m)
at FSharp.Formatting.ApiDocs.SymbolReader.readCommentsInto[c](FSharpSymbol sym, ReadingContext ctx, String xmlDocSig, FSharpFunc`2 f)
at FSharp.Formatting.ApiDocs.SymbolReader.tryReadMember(ReadingContext ctx, String entityUrl, ApiDocMemberKind kind, FSharpMemberOrFunctionOrValue memb)
It looks like mfvToCref expects every entity reachable from a member signature to have been registered up front, but the abbreviated types from FSharp.Core and the BCL (System.Tuple, FSharpList, System.String) never are. Expected: the abbreviation's own comment is read regardless of whether the target type can be cross-referenced, and unresolvable targets simply do not get a link.
Environment: fsdocs-tool 23.0.0-alpha.1, Linux, .NET SDK 11.0.100-rc.1.
Summary
fsdocs (23.0.0-alpha.1) fails to read the XML comments of type abbreviations whose target is a tuple, a list or
string, loggingCould not read comments from entity ... The entity System.Tuple2 was not registered before!`. The comments on those abbreviations are then dropped from the generated API docs.Repro
Building the API docs for
FSharp.Compiler.Servicefrom https://github.com/dotnet/fsharp gives 20 of these. The abbreviation and the type that the resolver stumbles on:Minimal equivalents:
Stack trace:
It looks like
mfvToCrefexpects every entity reachable from a member signature to have been registered up front, but the abbreviated types from FSharp.Core and the BCL (System.Tuple,FSharpList,System.String) never are. Expected: the abbreviation's own comment is read regardless of whether the target type can be cross-referenced, and unresolvable targets simply do not get a link.Environment: fsdocs-tool 23.0.0-alpha.1, Linux, .NET SDK 11.0.100-rc.1.