Exclude members with CompilerMessageAttribute(IsHidden=true) from API docs

Members and functions annotated with [<CompilerMessage(..., IsHidden=true)>] are now
automatically treated as excluded from API documentation, equivalent to [omit] or <exclude/>.

Closes #144

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 2 people

RELEASE_NOTES.md

@@ -11,6 +11,7 @@
 * HTML-encode XML doc text nodes and unresolved `<see cref>` values to prevent HTML injection and fix broken output when docs contain characters like `<`, `>`, or backticks in generic type notation. [#748](https://github.com/fsprojects/FSharp.Formatting/issues/748)
 * Add uppercase output kind extension (e.g. `HTML`, `IPYNB`) to `ConditionalDefines` so that `#if HTML` and `(*** condition: HTML ***)` work alongside their lowercase variants. [#693](https://github.com/fsprojects/FSharp.Formatting/issues/693)
 * Strip `#if SYMBOL` / `#endif // SYMBOL` marker lines from `LiterateCode` source before syntax-highlighting so they do not appear in formatted output. [#693](https://github.com/fsprojects/FSharp.Formatting/issues/693)
+* Members and functions annotated with `CompilerMessageAttribute(IsHidden=true)` are now automatically excluded from API docs, matching the behaviour of `[omit]` / `<exclude/>`. [#144](https://github.com/fsprojects/FSharp.Formatting/issues/144)
 
 ### Changed
 * Update FCS to 43.10.100. [#935](https://github.com/fsprojects/FSharp.Formatting/pull/966)

src/FSharp.Formatting.ApiDocs/GenerateModel.fs

@@ -2398,6 +2398,21 @@ module internal SymbolReader =
                 | Command "exclude" v
                 | Let "false" (v, _) -> (v <> "false")
 
+            let isCompilerHidden =
+                let attribs =
+                    match sym with
+                    | :? FSharpMemberOrFunctionOrValue as mfv -> mfv.Attributes :> FSharpAttribute seq
+                    | :? FSharpEntity as ent -> ent.Attributes :> FSharpAttribute seq
+                    | _ -> Seq.empty
+
+                attribs
+                |> Seq.exists (fun a ->
+                    a.AttributeType.FullName = "Microsoft.FSharp.Core.CompilerMessageAttribute"
+                    && a.NamedArguments
+                       |> Seq.exists (fun (_, name, _, value) -> name = "IsHidden" && (value :?> bool) = true))
+
+            let exclude = exclude || isCompilerHidden
+
             try
                 Some(f cat catindex exclude cmds comment, nsdocs)
             with e ->

tests/FSharp.ApiDocs.Tests/ApiDocsTests.fs

@@ -179,6 +179,9 @@ let ``ApiDocs excludes items`` (format: OutputFormat) =
     files.[(sprintf "fslib-partiallydocumented.%s" format.Extension)]
     |> shouldNotContainText "shouldBeExcluded7"
 
+    files.[(sprintf "fslib-partiallydocumented.%s" format.Extension)]
+    |> shouldNotContainText "shouldBeExcludedCompilerHidden"
+
     // We can only expect a warning for "wishItWasExcluded1" & "WishItWasExcluded2"
 
     files.ContainsKey(sprintf "fslib-partiallydocumented-notdocumented1.%s" format.Extension)

tests/FSharp.ApiDocs.Tests/files/TestLib3/Library3.fs

@@ -58,4 +58,7 @@ module PartiallyDocumented =
     module NotDocumented3 =
         let a = 10
 
+    [<CompilerMessage("Internal helper, hidden from IntelliSense", 9999, IsHidden = true)>]
+    let shouldBeExcludedCompilerHidden x = x
+
     let x = 10