Questions: inheritedoc and filter out Field section on output about shfb

[kevin-galil]

Here is the source that got filtered out:

namespace TestName
{
  /// <summary>
  /// Class that defines values for the Galil C Library return codes.
  /// </summary>
  /// <remarks>
  /// The following is a list of error code ordered by its value
  /// <list type="table">
  /// <listheader>
  /// <term>Error Code Flag</term>
  /// <term>Error Code Value</term>
  /// <term>Description</term>
  /// </listheader>
  /// <listheader>
  /// <term><c><see cref="G_NO_ERROR"/></c></term>
  /// <term>0</term>
  /// <term><inheritdoc cref="G_NO_ERROR" select="summary"/></term>
  /// </listheader>
  /// <listheader>
  /// <term><c><see cref="G_NO_ERROR"/></c></term>
  /// <term>0</term>
  /// <term><inheritdoc cref="F:TestName.TestClass.G_NO_ERROR" select="summary"/></term>
  /// </listheader>
  /// </list>
  /// </remarks>
  public static class TestClass
  {
    /// <summary>Return value if function succeeded.</summary>
    public const Int32 G_NO_ERROR = 0;      
    /// <summary>
    /// General library error. Indicates internal API caught an unexpected error. Contact Galil support if this error is returned, [email protected].
    /// </summary>
    public const Int32 G_GCLIB_ERROR = -1;
  } 
}

[EWSoftware]

I had to go back and look at the documentation for inheritdoc. When used in a nested element, it inherits the parent elements in the filter if the expression isn't rooted. So, in your example, it's actually looking for remarks/list/listheader/term/summary. In order to force it to look at the root, you need to include the leading backslash and use the node() method to tell it where to get the comments.

The API filter should work. Another alternative is to add exclude elements to the members. An example for both this and the issue above is shown below.

Since these are integer values, another alternative would be to use an enumeration which solves both issues and gives you the format you want without having to keep the table in synch with the members. However that would probably be a breaking change. An example is shown below too.

namespace TestName
{
    /// <summary>
    /// Class that defines values for the Galil C Library return codes.
    /// </summary>
    /// <remarks>
    /// The following is a list of error code ordered by its value
    /// <list type="table">
    /// <listheader>
    /// <term>Error Code Flag</term>
    /// <term>Error Code Value</term>
    /// <term>Description</term>
    /// </listheader>
    /// <item>
    /// <term><c>G_NO_ERROR</c></term>
    /// <term>0</term>
    /// <term><inheritdoc cref="G_NO_ERROR" select="/summary/node()" /></term>
    /// </item>
    /// <item>
    /// <term><c>G_GCLIB_ERROR</c></term>
    /// <term>-1</term>
    /// <term><inheritdoc cref="G_GCLIB_ERROR" select="/summary/node()" /></term>
    /// </item>
    /// </list>
    /// </remarks>
    public static class TestClass
    {
        /// <summary>Return value if function succeeded.</summary>
        /// <exclude />
        public const Int32 G_NO_ERROR = 0;
        /// <summary>
        /// General library error. Indicates internal API caught an unexpected error. Contact Galil support if this error is returned, [email protected].
        /// </summary>
        /// <exclude />
        public const Int32 G_GCLIB_ERROR = -1;
    }

    /// <summary>
    /// Test enum
    /// </summary>
    public enum TestEnum
    {
        /// <summary>Return value if function succeeded.</summary>
        G_NO_ERROR = 0,
        /// <summary>
        /// General library error. Indicates internal API caught an unexpected error. Contact Galil support if this error is returned, [email protected].
        /// </summary>
        G_GCLIB_ERROR = -1
    }
}

[kevin-galil]

Thank you for your quick and helpful response again. Both the solution and enum idea works out great. Even though I like the enum solution, we will end up using constants due to number of casting happens in the code when checking error code returns from C DLL.

Thank you again for your time and support.