[omit] vs <exclude/>

[davedawkins]

% dotnet fsdocs --version
fsdocs 16.1.1
% dotnet --version
6.0.404

Both [omit] and <exclude> are mentioned in the documentation.

However:

• <exclude> doesn't appear to work (neither does <exclude/>)
• [omit] does work, but:
  • it produces a warning
  • sometimes it doesn't and becomes the summary for the item being excluded.

The warning (which gives a good example of how to use <exclude/>:

The use of `[omit]` and other commands in XML comments is deprecated, please use XML extensions, see https://github.com/fsharp/fslang-design/blob/master/tooling/FST-1031-xmldoc-extensions.md

When [omit] doesn't work:

[davedawkins]

For reference, BindHelpers is an internal module. Eg

[<AutoOpen>]
module Sutil.Bindings

///[omit]
[<AutoOpen>]
module BindHelpers =
    // ..

[nojaf]

Hello, I can't say I know anything about this. I found both exclude and omit in https://github.com/fsprojects/FSharp.Formatting/blob/94e833aa3d741e70b75f7d3d8f52da44d364f59c/src/FSharp.Formatting.ApiDocs/GenerateModel.fs so there definitely is something about it.
I'm afraid you would have to debug that code to really know what is up.

[davedawkins]

Verified that it doesn't work in 17.2 either

% dotnet --version
7.0.101
% dotnet fsdocs --version
fsdocs 17.2.0

I have tried:

///<exclude>
/// <exclude>
///<exclude/>
/// <exclude/>
/// <exclude> </exclude>
/// <exclude value="true">true</exclude>

From your link:

        for e in doc.Elements(XName.Get "exclude") do
            cmds.["exclude"] <- e.Value

        for e in doc.Elements(XName.Get "omit") do
            cmds.["omit"] <- e.Value

My guess is that either:

• exclude isn't being parsed into doc.Elements or
• e.Value isn't set correctly for <exclude/> or
• cmds ["exclude"] is being ignored somewhere

If you're a maintainer, could you point me at the code that assigns/parses/builds doc.Elements please?

[davedawkins]

I'm writing a test for <exclude/> and [omit]

[nojaf]

I can't really say I know anything more than you do at this point.
I found a let doc = XDocument.Load(xmlFile) call in that same file, so interestingly enough it is grabbing the XML from a separate file and something embedded in the assembly, I guess.
Or not, I honestly don't know and won't be of much use here.
Good luck!

[davedawkins]

OK :-) Well, I'm down the rabbit hole now - I'll keep at it. I don't have a lot of success with fsdocs.

[nojaf]

Thank you!

[davedawkins]

OK, so part of the problem is that

/// A comment
/// <exclude/>

is parsed as

<summary>A comment&lt;exclude/&gt</summary>

This means a workaround is to explicitly tag the comment

/// <summary>
/// A comment
/// </summary>
/// <exclude/>

[davedawkins]

Nested modules are still included though.

[davedawkins]

Fixed it. PR incoming

[davedawkins]

PR submitted and passed checks

[nhirschey]

Closed by #787