Override summary descriptions for inherited fields

Topics: User Forum
Aug 22, 2012 at 3:37 PM

Is there a way to override the summary description of inherited field members for a class?

For example, say I have classes:

public class BaseEntity
{
   /// <summary>
   /// Entity-specific identification code
   /// </summary>
   public string code;

   /// <summary>
   /// Entity name
   /// </summary>
   public string name;
}

public class StateEntity : BaseEntity
{
   /// <summary>
   /// State abbreviation
   /// </summary>
   public abbreviation;
}

public class CountyEntity : BaseEntity
{
   /// <summary>
   /// County population
   /// </summary>
   int population;
}

With DocumentInheritedMembers set to True, Sandcastle includes the BaseEntity class fields code and name in the StateEntity Members and CountyEntity Members help pages with the summary descriptions from the BaseEntity, e.g. for StateEntity:

StateEntity Fields

  Name Description
  abbreviation State or province abbreviation
  code Entity-specific identification code (Inherited from BaseEntity.)
  name Entity name (Inherited from BaseEntity.)

 

However, what I would like to do is be able to override the summary description for these inherited fields.  For example, for StateEntity I would like the field descriptions to read:

StateEntity Fields

  Name Description
  abbreviation State or province abbreviation
  code Two-digit state ANSI code (Inherited from BaseEntity.)
  name State name (Inherited from BaseEntity.)

I have tried adding to my Sandcastle project an additional XML file (in addition to the one generated for my assembly) as a documentation source where I have added custom field summaries for the inherited classes, e.g.:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>MyAssembly</name>
    </assembly>
    <members>
        <member name="F:MyNamespace.StateEntity.code">
            <summary>
            Two-digit state ANSI code
            </summary>
        </member>
        <member name="F:MyNamespace.StateEntity.name">
            <summary>
            State name
            </summary>
        </member>
    </members>
</doc>

But this doesn't work ... I still get the field summaries from the base class.

Is is possible to override the description of inherited fields in Sandcastle?  If so, what do I need to do?

Any help is greatly appreciated.

Thanks,

Brian

Coordinator
Aug 22, 2012 at 4:19 PM

Since they are inherited, there is no way to override the documentation as the members and the related documentation will always come from the base class.  There's nowhere in the derived class from which to obtain alternate documentation.  One option would be to make the base class abstract and make those two member abstract properties rather than fields to force them to be implemented in the derived classes.  At that point, there would be a derived member to which you could attach the class-specific documentation.

Eric