revisionHistory

This element is used to display revision history for a type or its members. It originated in the old NDoc and VBCommenter tools but is still useful today to communicate revision history in the documentation.

Syntax

This top-level element is valid on all types and type members.

 
<revisionHistory [visible="true|false"]>
  <revision date="MM/dd/yyyy" version="#.#.#.#" [author="XXXXX"] [visible="true|false"]>
    Comments about the revision.
  </revision>
</revisionHistory>

  Note

This is a custom XML comments element implemented by the Sandcastle Help File Builder. It will not appear in the list of valid elements for XML comments IntelliSense.

An optional visible attribute on the revisionHistory parent element controls visibility of the section within the generated topic. If omitted or set to true, the revision history is included. If set to false, it is not included in the topic.

The revision elements describe one or more revisions to the type or member. The following attributes are supported:

date

This attribute specifies the date of the revision. The value is treated as a string field and is displayed as-is in the generated help topic. No locale date formatting is applied.

version

This attribute specifies the version in which the revision was made. As with the date, the value is treated as a string field and is displayed as-is in the generated help topic.

author

This attribute is optional and specifies the name of the person that made the revision. This attribute's value will not appear in the generated help topic.

visible

This optional attribute can be used to control visibility of the revision in the generated topic. If omitted or set to true, the revision entry is included. If set to false, it is not included in the topic.

The content of the revision element can contain other XML comments elements similar to a remarks section to add additional details.

Example

 
/// <summary>
/// This class demonstrates the revision history
/// </summary>
/// <remarks>The revision history element can be used on the class and its
/// members.</remarks>
/// <revisionHistory>
///     <revision date="04/11/2014" version="9.0.1.0" author="THLUCAS">This
/// revision will be displayed since the "visible" attribute is not present
/// (i.e. default).</revision>
///     <revision date="04/12/2014" version="9.0.1.1" author="THLUCAS"
/// visible="true">This revision will be displayed due to it's
/// "visible=true" attribute setting.</revision>
///     <revision date="04/15/2014" version="9.0.1.2" author="THLUCAS"
/// visible="false">This revision will NOT be displayed due to it's
/// "visible=false" attribute setting.
///     </revision>
///     <revision date="04/20/2014" version="9.0.1.3" author="THLUCAS">
///         <para>This revision will be displayed since the "visible"
/// attribute is not present (i.e. default).</para>
/// 
///         <para>Other XML comments elements are supported here and can be
/// used as in a remarks section to add additional details.</para>
/// 
///         <list type="bullet">
///             <item>Point #1</item>
///             <item>Point #2</item>
///             <item>Point #3</item>
///         </list>
///     </revision>
/// </revisionHistory>
/// <conceptualLink target="2a973959-9c9a-4b3b-abcb-48bb30382400"/>
public class RevisionHistoryClass
{
    /// <summary>
    /// This property has revision history
    /// </summary>
    /// <revisionHistory>
    ///     <revision date="05/25/2014" version="9.0.1.4"
    /// author="EWOODRUFF">Added an example property</revision>
    /// </revisionHistory>
    public string Revision { get; set; }

    /// <summary>
    /// This method has revision history
    /// </summary>
    /// <revisionHistory>
    ///     <revision date="05/25/2014" version="9.0.1.4"
    /// author="EWOODRUFF">Added an example method</revision>
    /// </revisionHistory>
    public void ExampleMethod()
    {
    }
}

See Also