The best solution for formatting the text in @-style comments seems to be using macros directly in comments. Macros are defined and used in templates but they can be called directly from comments as well. User can define any number of macros. Macro calls are replaced by their text during compilation. The source code using macros doesn't depend on output format, so you can use it with every template supporting given macro. Thus, e.g. for bold text the same macro is used which is defined in each template using the proper specific syntax.

Example

This is modified example using formatting directives so that it can be used with every output format. First we need to define macro for bold text in every template (it is already predefined in all templates). Let the opening macro for bold be $b$ and closing $bb$. In every HTML based template (Help 2, HTML and CHM) define these macros as follows:

$b$ <b>

$bb$ </b>

And in RTF template define these macros as follows:

$b$ {\b_

$bb$ }

Important, don't forget to type one space character after "{\b" instead of red underscore! The reason is explained bellow.

Now we can use our macros everywhere in the VSdocman comments:

    '**

    'Sample method with one String argument.

    '@param        x The first parameter.

    '@return       $b$True$bb$ if no error occurs.

    Function method1(ByVal x As String) As Boolean

Remarks

You can call all macros and commands provided by VSdocman, not only those defined by user. But you should be very careful and do it only when really necessary.

When defining new macros for some output formats you should realize and respect some facts related to given format. For example, tags in RTF format must be separated from following text by space. This is the reason why there is a space after every formatting macro body in all RTF based templates. If you omit this space in definition, you should include space in VSdocman comment after macro call, otherwise RTF reader won't recognize it.

Note, macro usage can be also applied to the title page text in the Options dialog.

See Also

$EOL$ macro usage | $CODE$ and $END-CODE$ macros usage | Formatting Documentation Directly in Comments