Using HTML Markup in Class Documentation

You can use HTML tags within the comments in a class. In your markup, adhere to as strict an HTML standard as you can, for example XHTML, so that any browser can display the result. Note that the %CSP.DocumaticOpens in a new tab class generates a complete HTML page, and the class documentation is contained within the <body> element on that page. Therefore, do not include the HTML tags <html>, <body>, <head>, or <meta> in your markup; these tags will all be ignored. Also, the class name is displayed as a <h1> heading, so if you use headings, use <h2> and lower headings. Because search engines favor HTML pages that have exactly one <h1>, if you include <h1> within your markup, that heading is converted to <h2>.

In addition to standard HTML, you can use the following tags: <CLASS>, <METHOD>, <PROPERTY>, <PARAMETER>, <QUERY>, and <EXAMPLE>. (As with standard HTML tags, the names of these tags are not case-sensitive.) The most commonly used tags are described here. See the documentation for %CSP.DocumaticOpens in a new tab for details of the others.

<CLASS>

Use to tag class names. If the class exists, the contents are displayed as a link to the class’ documentation. For example:

/// This uses the <CLASS>MyApp.MyClass</CLASS> class.

Use to tag programming examples. This tag affects the appearance of the text. Note that each /// line becomes a separate line in the example (in contrast to the usual case, where the lines are combined into a single paragraph). For example:

/// <EXAMPLE>
/// set o=..%New()
/// set o.MyProperty=42
/// set o.OtherProp="abc"
/// do o.WriteSummary()
/// </EXAMPLE>

Use to tag method names. If the method exists, the contents are displayed as a link to the method’s documentation. The method cannot be internal and is assumed to be available in the same class. For example:

/// This is identical to the <METHOD>Unique</METHOD> method.

<PROPERTY>,

Use to tag property names. If the property exists, the contents are displayed as a link to the property’s documentation. The property cannot be internal and is assumed to be available in the same class. For example:

/// This uses the value of the <PROPERTY>State</PROPERTY> property.

Here is a multi-line description using HTML markup:

/// The <METHOD>Factorial</METHOD> method returns the factorial
/// of the value specified by <VAR>x</VAR>.