Summary of commonly used HTML elements

Write the text of an ASDoc comment in XHTML-compliant HTML. That means your HTML syntax has to conform to XML syntax rules. For example, close all HTML tags, such as <p> and <code> tags, by inserting the closing </p> or </code> tag.

The following table lists commonly used HTML tags and character codes within ASDoc comments:

Tag or Code

Description

 
<p>

Starts a new paragraph. You must close <p> tags.

Do not use <p> for the first paragraph of a doc comment (the paragraph after the opening /**) or the first paragraph associated with a tag. Use the <p> tag for subsequent; for example:

/**

* The first sentence of a main description.

*

* <p>This line starts a new paragraph.</p>

*

* <p>This line starts a third paragraph.</p>

*/

ASDoc ignores white space in comments. To add white space for readability in the AS file, do not use the <p> tag but add blank lines.

 
class="hide"

Hides text. Use this tag if you want to add documentation to the source file but do not want it to appear in the output.

 
<listing>

Indicates a program listing (sample code).

Use this tag to enclose code snippets that you format as separate paragraphs, in monospace font, and in a gray background to distinguish the code from surrounding text. Close all <listing> tags. 

<pre>

Formats text in monospace font, such as a description of an algorithm or a formula. Do not use <br/> tags at end of line.

Use <listing> tag for code snippets. 

<br>

Adds a line break. You must close this tag.

Comments for most tags are automatically formatted; you do not generally have to add line breaks. To create additional white space, add a new paragraph instead.

This tag might not be supported in the future, so use it only if necessary. 

<ul>, <li>

Creates a list. You must close these tags.

 
<table><th><tr><td>

Creates a table. For basic tables that conform to ASDoc style, set the class attribute to innertable. Avoid setting any special attributes. Avoid nesting structural items, such as lists, within tables.

ASDoc uses a standard CSS stylesheet that has definitions for the <table>, <th>, <tr> and <td> tags. You must close these tags.

Use <th> for header cells instead of <td>, so the headers get formatted correctly.

 
<img>

Inserts an image. To create the correct amount of space around an image, enclose the image reference in <p></p> tags. Captions are optional; if you use a caption, make it boldface. You must close the <img> tag by ending it with />, as the following example shows:

<img src = "../../images/matrix.jpg" />
 
<code>

Applies monospace formatting. You must close this tag.

 
<strong>

Applies bold text formatting. You must close this tag.

 
<em>

Applies italic formatting. You must close this tag.

 
&lt;

Less-than operator (<) . Ensure that you include the final semicolon (;).

 
&gt;

Greater-than operator (>). Ensure that you include the final semicolon (;).

 
&#38;

Ampersand (&). Do not use &amp;. Ensure that you include the final semicolon (;).

&#42;

Do not use a literal “*” character in the body of a comment; instead, insert the HTML character code &#42;.

 
&#x2014;

Em dash. Ensure that you include the final semicolon (;).

 
&#x99;

Trademark symbol (™) that is not registered. This character is superscript by default, so do not enclose it in <sup> tags. Ensure that you include the final semicolon (;).

 
&#xA0;

Nonbreaking space. Ensure that you include the final semicolon (;).

 
&#xAE;

Registered trademark symbol (®). Enclose this character in <sup> tags to make it superscript. Ensure that you include the final semicolon (;).

 
&#xB0;

Degree symbol. Ensure that you include the final semicolon (;).

 
&#64;

Do not use an @ sign in an ASDoc comment; instead, insert the HTML character code: &#64;.