Inserting Comments

When you enter text in the Topic Editor Doc-O-Matic inserts your comments in the location you select as topic location. You can determine how to insert comments in your source code (C++, C#, Delphi, IDL, Java, JavaScript, VB.NET, MATLAB, ASPX, PHP and JSP) or in a DTX file.

If you use sections to structure your topics section starters are inserted in your source code. A topic consisting of a Summary and a Parameters section will look like this:

// Summary
// Locates a sting in this string list.
//
// Parameters
// S   -    The string to be located
// Index -  The index of S is returned.

To change comment settings

On the following Settings pages you can determine:

To determine	Select
Where comment blocks are placed	Comment Finding
Which comment characters are used	Comment Characters
What length text blocks may have	Editor Options
What minimum width the comments will have	Comment Options
Whether or not only /// comment characters are used	Comment Finding
How much comments are indented	Comment Options
Whether or not topic IDs are inserted in your source code	Topic ID Insertion
Whether or not tokens are used	Token
Whether or not comment characters start or end on a separate line	Comment Options
Whether or not only XML conform tags are used	Documentation Standard

To change section settings

Choose which section headings are inserted. On the Sections page enter the section starter that you want to insert as section heading at the top of the list in the Starters box of the corresponding section.
Use section delimiters. Select the Always use section delimiters check box on the [General Settings] > Editor > Comments page.
Insert trimmed lines before section starters. Select the Insert trim line as separator before section headings check box on the [General Settings] > Editor > Comments page.
Use Javadoc tags as comment standard. On the Documentation Standard page select Javadoc tags. Only for C++, C#, Delphi, IDL, Java, JavaScript, VB.NET, MATLAB, ASPX, PHP and JSP source code.
Use XMLDoc tags as comment standard. On the [General Settings] > Editor > Standard page select the XMLDoc tags check box. Only for C++, C#, Delphi, IDL, Java, JavaScript, VB.NET, MATLAB, ASPX, PHP and JSP source code.
Only insert tags that conform to the XML standard. On the [General Settings] > Editor > Standard page select the XMLDoc compatible tags check box

To format comments

Doc-O-Matic uses the first character entered in the corresponding box on the [General Settings] > Documentation > Special Characters page, to format
- bulleted lists
- table alignments and headings
- and headings
To replace these characters enter them as first characters in the corresponding box.
To draw walls around your comments, select the Walls check boxes on the [General Settings] > Editor > Comments page and enter the characters you want to use for your walls.
To draw all walls using the same width select a width in Minimum width of comment on the [General Settings] > Editor > Comments page.

Notes

If the option Always use section delimiters on the [General Settings] > Editor > Comments page is turned on, Doc-O-Matic uses the first starter delimiter that appears in the starter delimiter list on the [General Settings] > Sections > Delimiters page.

Related Settings

Comment Finding, Comment Characters, Editor, Comment Options, Documentation Standard

Applies to: Doc-O-Matic Professional.