Questions: inheritedoc and filter out Field section on output

[kevin-galil]

I have a static class just for constants (ported from C/C++'s global #define). The general idea is instead of lots field member pages, we will have a table in remarks section that lists field name, value, summary. Like https://msdn.microsoft.com/en-us/library/windows/desktop/ms681388(v=vs.85).aspx knowing the document at that link is NOT generated from source. However, the requirement is that it has to generate from source.

I am trying to insert content of summary section of a field into its class' remarks section.
I tried

and

and both generates nothing

The second question is how do I disable the Fields section of output. The API filter allows me to uncheck it but it does not look like its saving the setting when I build. Also note this class has ONLY fields info, which I think could be the issue.

Thanks again for your help.

********** Source Code **************
namespace TestLib
{
///

/// Class that defines values for return codes.
///

///
/// The following is a list of error code ordered by its value
///
///
/// Error Code Flag
/// Error Code Value
/// Description
///
///
///
/// 0
///
///
///
///
/// -1
///
///
///
///
public static class TestClass
{
///

Return value if function succeeded.

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, softwaresupport@galil.com.
/// </summary>


public const Int32 G_GCLIB_ERROR = -1;

}
}
********** Source Code **************

[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, softwaresupport@galil.com.
    /// </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, softwaresupport@galil.com.
        /// </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, softwaresupport@galil.com.
        /// </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.