Skip to content

Missing-docs warning FD0001 reported for compiler-generated union case IsXxx properties #1313

Description

@nojaf

Summary

With FsDocsWarnOnMissingDocs enabled, fsdocs (23.0.0-alpha.1) reports FD0001: no documentation for the compiler-generated IsXxx union case tester properties. These properties are synthesized by the F# compiler for every union case and cannot carry XML documentation in source, so the warnings are noise that no source change can fix.

Repro

Building the API docs for FSharp.Compiler.Service from https://github.com/dotnet/fsharp with <FsDocsWarnOnMissingDocs>true</FsDocsWarnOnMissingDocs>:

src/Compiler/AbstractIL/il.fsi(158,6): warning FD0001: no documentation for 'P:FSharp.Compiler.AbstractIL.IL.ILArgConvention.IsDefault'
src/Compiler/AbstractIL/il.fsi(160,6): warning FD0001: no documentation for 'P:FSharp.Compiler.AbstractIL.IL.ILArgConvention.IsStdCall'
src/Compiler/AbstractIL/il.fsi(161,6): warning FD0001: no documentation for 'P:FSharp.Compiler.AbstractIL.IL.ILArgConvention.IsThisCall'

For that one assembly, 1059 of the 2073 FD0001 warnings are for .Is<CaseName> properties on union types, so about half of the missing-docs output is unfixable.

A minimal repro is any documented union:

/// A convention
type Convention =
    /// The default
    | Default
    /// Standard call
    | StdCall

fsdocs then warns about P:...Convention.IsDefault and P:...Convention.IsStdCall.

Suggestion

Skip the missing-docs warning (and arguably the members altogether, or document them as "true if this is the X case") for union case tester properties. They are identifiable as properties named Is<CaseName> on a union entity where <CaseName> matches one of entity.UnionCases, or via IsUnionCaseTester on FSharpMemberOrFunctionOrValue if FCS exposes it in the version you build against.

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