Skip to content

Comments dropped for type abbreviations of tuples, lists and string: "entity was not registered before" #1314

Description

@nojaf

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions