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.
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.
|VB 3.0-6.0 projects||VB.NET projects|
Comment manual includes a section for:
Declare and Event statements are not included in Comment manual.
Comment manual includes a section for:
For each section, comments are included above and below the procedure or module header line.
For procedures with no
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.
|2||'[param] descr||Parameter table|
|3||'[*n*] [..]||Other table with n columns|
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
Escape character. By adding a colon : as the first character in a comment, you can tell Project Printer to handle it as a regular non-heading line. This is useful when you need to use a colon in the comment text. 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 little 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 by using the following syntax.
' [*3*] [Heading1] [Heading2] [Heading3] ' [a] [b] [c] ' [d] [[e]] [f]
[*n*] marks the start of a table with n columns of equal width. The [Headings] after [*n*] create bold column headings for the table. If you don't want headings, just put the [*n*] command alone on a line.
The maximum number of columns is 5. A table ends when there are no more commented lines with square brackets.
Use double brackets to put bracketed content in the table. You can use this syntax to mark an optional parameter, for example. However, you should not use any other brackets as it is likely to make Project Printer 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 As Integer, y As Integer, Text As String) 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 ' ~Don't show this line ' Return value: ' True if successful ' False in case an error occurs ' Remarks: Calls Err.Raise 12345 if Text is 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 will get:
Function PrintText(x As Integer, y As Integer, Text As String) As Boolean
Prints text on the screen at (x, y)
True if successful
False in case an error occurs
Calls Err.Raise 12345 if Text is 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.
©Aivosto Oy - Project Analyzer Help Contents