Comment manual is a feature of Project Printer. It creates a document based on comments in your source code. You can use it as technical documentation for your program. You can also use it as a starting point for writing your own documents.
Comment manual utilizes procedure and module header comments to document your code. There are a few simple commentation syntax rules you must follow. If you have existing comments in your code and want to utilize them without reformatting them, see Comment manual with unformatted comments.
Comment manual includes a section for:
Sub, Function or Property line are included. Thus, all comments before the declaration line are included, as well as all comments after it up to an empty line or a normal code line.Declare and Event statements are not included in Comment manual.
Comment manual includes a section for:
Namespace, Module, Interface, Class and Structure block, including Partial Class and Partial Structure.Declare and Event statements are included (as opposed to classic VB).For each section, comments are included above and below the procedure or module header line.
Certain procedures consist of a single line only. There is no procedure body or End Sub line. Examples of such procedures are Declare and Event lines and interface methods. For these procedures, comments above the procedure declaration are are included, but not comments below it.
XML documentation comments. Comment manual can be used with XML documentation comments (''' syntax, introduced in VB 2005). However, no special processing or formatting is done on the XML comments. The Comment manual with unformatted comments option is potentially more useful with XML comments than the Comment manual with formatted comments.
Most comments are reported as found in the code. Comment markup is removed (', ''', Rem). Indentation is removed too. Comments starting with the dollar sign ($) or tilde (~) are hidden, as are any empty comment lines.
There are a few simple syntax rules for formatting the manual. These rules allow you to write comments that are readable both in the raw source code and in Comment manual.
| # | Syntax | Description |
|---|---|---|
| 1 | 'Heading: | Heading |
| 2 | '[param] descr | Parameter table |
| 3 | '[*n*] [..] | Formatted table with n columns |
| 4 | '~ '$ | Exclude line |
|
MyHeading Text line 1 Text line 2 :This function processes C: and D: but not E: |
You make a heading with a colon.
' MyHeading: Text line 1 ' Text line 2
The space is required after the colon to make Project Printer recognize this as a header line. Alternatively, you can put the heading on its own line as follows:
' MyHeading: ' Text line 1 ' Text line 2
In order to have a colon : on a regular line, start the comment with an extra colon. The extra colon tells Project Printer to handle it as a regular line, not a heading. Example:
' :This function processes C: and D: but not E:
|
Describe procedure parameters by putting the parameter name in square brackets, and describing the use of the parameter on the same line.
' [MyParameter1] MyDescription1 ' [MyParameter2] MyDescription2 ' [[MyParameter3]] MyDescription3
This will create a simple table with 2 columns and default headings. Use double brackets to display brackets in the table. You can use this syntax to mark an optional parameter, for example. You should not use any other brackets as it is likely to make Project Printer unable to parse the comment correctly.
A parameter table ends when there are no more commented lines with brackets. This also means that each parameter description must fit on one line.
|
Generate a formatted table with the following syntax:
' [*3*] [Heading1] [Heading2] [Heading3] ' [a] [b] [c] ' [d] [[e]] [f]
[*n*] marks the start of a formatted table with n columns of equal width. The maximum number of columns is 5.
You can add [Headings] after [*n*] in order to create bold column headings for the table. If you don't want headings, just put [*n*] alone on the line.
On the next lines, add cells of the table in square brackets. The table continues as long as there are comment lines with square brackets. When the first line without brackets is found, the table ends.
If you need to show brackets in a table cell, use double brackets such as [[e]]. You can use this syntax to for an optional parameter, for example. You should not use any other brackets as it can cause Project Printer to become unable to correctly parse the comment.
You may omit the brackets [ ] around the last column if the row has more than one column.
~ (tilde) or $ (dollar) at the start of a commented line prevents the line from being included in the manual.
This is an example of a commented procedure:
Function PrintText(x, y, Text) As Boolean
' Prints text on the screen at (x, y)
' [x] The x-coordinate in pixels
' [y] The y-coordinate in pixels
' [Text] The string that will be displayed
' ~This comment is hidden
' $This comment is hidden, too
' Return value:
' True if successful
' False in case an error occurs
' Remarks: Raises error 12345 if Text too long
' This comment is not included
' because an empty or a non-comment line
' ends the comment section.
Const TOO_LONG = 80
If Len(Text) > TOO_LONG Then
... (code continues)
End Function
This is what you get:
|
Function PrintText(x, y, Text) As Boolean Prints text on the screen at (x, y)
Return value True if successful False in case an error occurs Remarks Raises error 12345 if Text too long |
If you select Comment manual with unformatted comments, you get a report similar to Comment manual, but none of the comment syntax rules are in effect. All comments are simply copied to the report without removing any indentation or empty lines. This option is useful if you have existing comments in your code and want to utilize them without a rewrite.