Creating Class Documentation
Your InterSystems IRIS® server provides a web page called the InterSystems Class Reference, which displays automatically generated reference information for the classes provided by InterSystems, as well as for classes you have created. Informally, the Class Reference is known as Documatic, because it is generated by the class %CSP.DocumaticOpens in a new tab.
The URL has the following form, using the <baseURL> for your instance:
This web page has a different look and feel from the online Class Reference (because the latter is also connected to the rest of the online documentation).
Introduction to the Class Reference
The purpose of the Class Reference is to advertise, to other programmers, which parts of a class can be used, and how to use them. The following shows an example:
This reference information shows the definitions of class members, but not their actual implementations. For example, it shows method signatures but not their internal definitions. It includes links between elements so that you can rapidly follow the logic of the code. There is also a search option.
Creating Documentation to Include in the Class Reference
To create documentation to include in the Class Reference, create comments within the class definitions — specifically comments that start with ///. If you precede the class declaration with such comments, the comments are shown at the top of the page for the class. If you precede a given class member with such comments, the comments are shown after the generated information for that class member. Once you compile the class, you can view its generated class documentation the next time you open the Class Reference documentation. If you add no Class Reference comments, items that you add to a class or package appear appropriately in the lists of class or package contents, but without any explanatory text.
You can extend any existing Class Reference comments by modifying the class definition. The syntax rules for Class Reference comments are strict:
All Class Reference comments that describe a class or class member must appear in a consecutive block immediately before the declaration of the item that they describe.
Each line in the block of comments must start with three slashes: ///
Note that, by default, the presentation combines the text of all the /// lines and treats the result as single paragraph. You can insert HTML line breaks (<br>). Or you can use HTML formatting (such as <p> and </p>), as discussed in the subsection.
The three slashes must begin at the first (left-most) position in the line.
No blank lines are allowed within Class Reference comments.
No blank lines are allowed between the last line of the Class Reference comments and the declaration for the item that they describe.
The length of the Class Reference comment (all lines combined) must be less than the string length limit (which is extremely long). See “String Length Limit”.
Class Reference comments allow plain text, plus any standard HTML element and a small number of specialized elements.
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.
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:
/// set o=..%New()
/// set o.MyProperty=42
/// set o.OtherProp="abc"
/// do o.WriteSummary()
Use to tag method names. If the method exists, the contents are displayed as a link to the method's documentation. For example:
/// This is identical to the <METHOD>Unique</METHOD> method.
Use to tag property names. If the property exists, the contents are displayed as a link to the property's documentation. 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>.