Problem with "enum" parameters

Jan 21, 2009 at 6:26 PM
Hi,

I'm creating C++ help docs and everything seems to be working except for one strange issue. The documentation for any methods that have an enumeration as a parameter does not show up in the help file. I'm wondering if anybody has any suggestions or if you think it's a bug in Sandcastle itself. My XML comments for these methods are the same as for any other methods, and the parameter portion of the comment is normal as such:

/// <param name="myEnum">
/// description of the parameter
/// </param>

Thanks,
Tiana
Editor
Jan 22, 2009 at 8:19 PM
I was unable to duplicate the issue.  Can you post a more detailed code example including the enum?  If you're using the Sandcastle Help File Builder, you might try setting the CppCommentsFixup property to true.  It can fix a few issues with the way the C++ compiler generates the XML comments file but those problems are usually related to generics.

Eric
Jan 23, 2009 at 5:38 PM
Hi Eric,
Thanks for the reply. The fact that you were unable to duplicate the issue is interesting... Here is a code snippet from my .h file. I had to modify some comments and names for privacy reasons, but the general idea is there:

     /// <summary>
     /// ...
     /// </summary>
     public enum class XYZ
     {
         /// <summary>
         /// ...
         /// </summary>
         modeA = MODE_A,

         /// <summary>
         /// ...
         /// </summary>
         modeB =  MODE_B,

         /// <summary>
         /// ...
         /// </summary>
         modeAB = MODE_AB
     };


Then later in the same file, one of the methods that uses this enumeration:

         /// <summary>
         /// <para>
         /// This function ...
         /// </para>
         /// <para>
         /// The returned ...
         /// </para>
         /// </summary>
         /// <param name="mode">
         /// The <see cref="XYZ"/> to use when ...
         /// </param>
         /// <returns>
         /// A boolean value indicating...
         /// </returns>
         bool aFunction( XYZ^ mode);


The function's comments do not show up in the documentation help file. The XYZ enumeration comments do.

Thanks,
Tiana
Editor
Jan 23, 2009 at 8:46 PM
My C++ skills aren't what they used to be.  I just used "public enum XYZ" in my test rather than "public enum class XYZ".  Adding "class" is what makes the difference.  This is another case where the C++ compiler outputs a different method signature than what the Sandcastle tools expect.  It generates:

M:CppTest.TestClass`1.aFunction(System.ValueType!CppTest.XYZ!System.Runtime.CompilerServices.IsBoxed)

But the signature is supposed to be:

M:CppTest.TestClass`1.aFunction(System.Enum!CppTest.XYZ!System.Runtime.CompilerServices.IsBoxed)

Because of the mismatch, Sandcastle can't match the comments to the member.  You can edit the XML comments file to fix it manually before building the help file.  I'll add this as another case to fix up in SHFB too.

Eric
Jan 23, 2009 at 9:43 PM
I think I can safely switch my enum class over to a plain enum; if not, my alternative is to just do a search and replace in the xml file for "ValueType" -> "Enum" before generating the help docs.

Thank you! Your help was greatly appreciated.