Comment manual in Project Printer

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.

Which comments are included?

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:

  1. Each source file. Comments are included from the start of the (declarations) section up to the first empty line or code line.
  2. Each procedure. The comments immediately before and after the Sub/Function/Property declaration line are included. All comments before the declaration line are taken, 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:

  1. Each source code file.
  2. Each Namespace, Module, Interface, Class and Structure block, including Partial Class/Structure.
  3. Each procedure. 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.

  1. Comments above the header are included up to the previous real code line. Empty lines do not break the comments.
  2. Comments below the header are included down to the next empty line or code line. An empty line ends the comments.

For procedures with no End xxx line (such as Declares, Events and interface methods), comments are included above the procedure declaration, but not below it.

Comment syntax

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.

#SyntaxDescription
1'Heading:Heading
2'[param] descrParameter table
3'[*n*] [..]Other table with n columns
4'~
'$
Hide line

1. Heading

Heading example
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

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:

2. Parameter table

Parameter example
ParameterDescription
MyParameter1MyDescription1
MyParameter2MyDescription2
[MyParameter3]MyDescription3

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.

3. Other table

Table example
Heading1Heading2Heading3
abc
d[e]f

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.

4. Excluding a comment from the manual

~ (tilde) or $ (dollar) at the start of a commented line prevents the line from being included in the manual.

Example

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)

ParameterDescription
xThe x-coordinate in pixels
yThe y-coordinate in pixels
TextThe string that will be displayed

Return value
True if successful
False in case an error occurs

Remarks
Calls Err.Raise 12345 if Text is too long

Comment manual with unformatted comments

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.

Project Printer

©Aivosto Oy - Project Analyzer Help Contents