Skip to content

Remarks

Genevieve Warren edited this page Jun 24, 2022 · 3 revisions

The Remarks section provides usage information for a type or member and covers details that aren't obvious from the syntax, summary, parameter, or return value sections of the reference topic.

Abstract class

For abstract classes from which users will inherit, include a Notes to Inheritors subsection. In the subsection, you should at least specify the abstract members that need to be overridden in a derived class. To add this subsection, use the following XML element:

<block subset="none" type="overrides">
  When you inherit from <Class>, you must override the following members: {...}
</block>

Constructor

Constructors (and initializers) set initial values for certain properties on the class. For two or more properties that are initialized, you can optionally list the initial values in a table in the Remarks section of the constructor. Consider adding this information when the properties are initialized to values that might be non-intuitive or otherwise important to note.

Include a table when:

  • The user will often want to use most initial values but might want to change certain properties. When there are several members, it's useful to know what all the initial values are without having to go to each member topic individually.

  • The default values imply specific functionality.

When specifying the initial property values, insert the following boilerplate wording above the table:

The following table shows initial property values for an instance of the <Class> class.

To help users find this information, you can also make a reference to it at the class level. Include the following boilerplate sentence in the Remarks section of the class:

For a list of initial property values for an instance of the <Class> class, see the <Constructor> constructor.

Explicit Interface Implementation

Use the following boilerplate in the Remarks section:

This member is an explicit interface member implementation. It can be used only when the <CurrentType> instance is cast to an <InterfaceType> interface.