[omit] vs <exclude/> about fsharp.formatting

[davedawkins]

Fixed it. PR incoming

[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]

PR submitted and passed checks

[nhirschey]

Closed by #787