XML Doc comment generation adding empty garbage

[KevinRansom]

Opened on CodePlex by ReedCopsey

Given the latest 3.1.2 builds, the XML Documentation generated by the F# compiler is adding numerous extra "empty" entries, such as:

<doc>
<assembly><name>FSharp.Core</name></assembly>
<members>
<member name="">
</member>
<member name="">
</member>
<member name="">
</member>
<member name="">
</member>
<member name="">
</member>
<member name="">
</member>
<member name="T:Microsoft.BuildSettings.BuildDetails">
</member>

This causes some utilities that parse these files to have serious errors, such as the build scripts to generate documentation included in the ProjectScaffolding project..

comments
latkin wrote Oct 22, 2014 at 6:50 PM [x]
Do you know if this is a new behavior in 3.1.2? Or has it been present for other releases?

ReedCopsey wrote Oct 22, 2014 at 7:25 PM [x]
Not sure. Suspect it's relatively new, as those build scripts only recently started failing. Will try to narrow down when this occured originally, but it seems wrong in any case...

latkin wrote Nov 25, 2014 at 5:17 PM [x]
Any update on this one? Do you have a repro solution so that we can check if this is a new behavior or longstanding issue?

[forki]

/cc @ReedCopsey

[ReedCopsey]

A repro is available at https://github.com/ReedCopsey/XmlDocGenerationProblems/

Note that there is an F# library and a C# library in this project. Both are essentially identical, each containing 2 classes with one member each.

The C# project creates the following XML Doc comments:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>CSharpLibrary</name>
    </assembly>
    <members>
        <member name="T:CSharpLibrary.Class1">
            <summary>
            This is the main class in C#
            </summary>
        </member>
        <member name="P:CSharpLibrary.Class1.X">
            <summary>
            Member X
            </summary>
        </member>
    </members>
</doc>

The F# project creates:

<?xml version="1.0" encoding="utf-8"?>
<doc>
<assembly><name>Library1</name></assembly>
<members>
<member name="P:Library1.Class1.X">
<summary>
 Member X
</summary>
</member>
<member name="">

</member>
<member name="T:Library1.Class1">
<summary>
 This is the main class
</summary>
</member>
<member name="">

</member>
<member name="">

</member>
<member name="">

</member>
</members>
</doc>

This is using Visual F# 3.1.2.

Note the extra empty member generation. It appears that member information is generated for types/members even when there is no comment for them, and the member name/information is left empty.

[latkin]

Same question as on codeplex, is this longstanding behavior or recently introduced? Would be helpful in the effort to track down cause.

[ReedCopsey]

@latkin It appears to happen in previous releases, as well. It happened in VS 2012/F# 3.0 from what I can tell, and every release since.

[brodyberg]

Is there a goal to have whitespace be identical?

It would be interesting to throw this into addMember of writeXmlDoc in fsc.fs:

if verbose && id = System.String.Empty then dprintf "empty id"

Perhaps the root of the problem lies in tastops.fs around line 6734?

[ReedCopsey]

@brodyberg I don't think whitespace has to match - but the empty entries just seem flat out wrong, and cause issues with some parsers.

[ReedCopsey]

@brodyberg Thank you for the hint. That function provides a simple place to filter the written output.