<summary> tags ignored

Topics: Developer Forum
Mar 12, 2014 at 11:01 PM
Edited Mar 12, 2014 at 11:02 PM
I'm using SHFB 2014.2.15.0 Beta and VS2012 to generate a help web site (VS 2010 style doc) for a .NET 4.0 assembly. The assembly builds fine and generates its XML doc file which is consumed by SHFB. SHFB runs to completion without error, but appears to not detect any <summary> tags in my source code.

Here's an example type:
namespace Foo
{
    /// <summary>
    /// The state of a <see cref="Foo.Entity"/>
    /// </summary>
    public enum EntityState
    {
        /// <summary>
        /// The entity is unchanged.
        /// </summary>
        Unchanged = 0,

        /// <summary>
        /// The entity has been added.
        /// </summary>
        Added = 1,

        /// <summary>
        /// The entity has been modified.
        /// </summary>
        Modified = 2,

        /// <summary>
        /// The entity has been deleted.
        /// </summary>
        Deleted = 3,
    }
}
The generated XML doc file contains the following entries:
        <member name="T:Foo.EntityState">
            <summary>
            The state of a <see cref="T:Foo.Entity"/>
            </summary>
        </member>
        <member name="F:Foo.EntityState.Unchanged">
            <summary>
            The entity is unchanged.
            </summary>
        </member>
        <member name="F:Foo.EntityState.Added">
            <summary>
            The entity has been added.
            </summary>
        </member>
        <member name="F:Foo.EntityState.Modified">
            <summary>
            The entity has been modified.
            </summary>
        </member>
        <member name="F:Foo.EntityState.Deleted">
            <summary>
            The entity has been deleted.
            </summary>
        </member>
The type is public, as are its members. Yet, there is no summary information generated for the enum type and the Description of each member is empty.

I'm at a loss to see what I'm doing wrong. Any help would be appreciated.

Thanks.
Coordinator
Mar 13, 2014 at 2:48 AM
Make sure you've got the right build configuration selected (Debug | AnyCPU, Release | AnyCPU). That's a common cause of incorrect comments showing up. Check the build log too. It will tell you which XML comments file it found. Check that one to make sure it is up to date.

Eric
Mar 13, 2014 at 4:13 AM
The build config is correct. I verified the XML file is being correctly generated by tweaking and comment and seeing the change in the XML file. SHFB's log identifies the correct XML file. There are no errors in the SHFB run, just a few warnings for missing
comments (for members that in fact are missing comments). These are the same warnings I see in VS2012 when I rebuild the project. Very strange, indeed. I've used SHFB a couple of years ago with much success. Will need to dig deeper. --Ravi
Mar 13, 2014 at 4:52 PM
Found the problem - SHFB's Platform Explorer's "Documentation Sources" node only included my assembly, not the .xml file. It wasn't obvious that the XML file needed to be added here, since it was automatically picked up by SHFB at run time. Explicitly
adding the XML file caused the doc to be generated. --Ravi