Go to Add-Ins -> VSdocman menu or press VSdocman button on standard toolbar. Options dialog appears. Set Comment - Indentation page.

 

 

Indent Modes of the Comments

Normally all @-style comment text is processed as is. It means that all whitespaces occurring at the beginning of each comment line, immediately after comment quote are not ignored and go to resulting documentation file. The format of comments should be like this:

'**

'@rem This is my

' text that will appear

' in the remarks section.

Resulting text in documentation file is:

 "This is my text that will appear in the remarks section."

This is shown properly in all document formats.

The problem arises, if someone wants to have nice, indented comments like this:

'**

'@rem This is my

'     text that will appear

'     in the remarks section.

Resulting text in documentation file is:

 "This is my     text that will appear     in the remarks section."

Those multiple spaces in the text are no problem for HTML and CHM formats, this sentence is shown correctly:

 "This is my text that will appear in the remarks section."

However, the output in RTF document looks exactly as its source:

 "This is my     text that will appear     in the remarks section."

To avoid this, user can tell VSdocman to ignore all multiple whitespaces at the beginning of comment lines by checking Ignore indentation option. All leading whitespaces are replaced by one space and documentation looks good even in RTF or HLP format.

Sometimes it is good to have indents in documentation even in "ignore indent" mode. For example when using short code sample directly in comments. For this purpose you must insert quote character at the beginning of line, immediately after comment quote. After that quote you can have indent which is not removed by VSdocman. Instead, leading quote is removed, so it doesn't appear in documentation. So following comment

'**

'@rem This is an example

'     of using myColor property:$EOL$

''       myColor = 1

looks in RTF like this:

"This is an example of using myColor property:

       myColor = 1"

The last problem is, when user wants to have leading quote character in resulting documentation. As shown above, if the first character after comment quote is a quote character, it is removed. So following comment

'**

'@rem On the next line

'I want to have some string in quotes$EOL$

''my string'

looks in RTF like this:

"On the next line I want to have some string in quotes

my string'"

The solution is very easy, just insert a space before leading quote:

'**

'@rem On the next line

'I want to have some string in quotes$EOL$

' 'my string'

And the result is:

"On the next line I want to have some string in quotes

'my string'"

Summary

1. If you are not using indents, use "don't ignore indent" mode.
2. Otherwise, use "ignore indent" mode.
3. If using "ignore indent" mode and some indent is necessary, use leading quote.
4. If using "ignore indent" mode and leading quote is supposed to appear in documentation, just insert space before it.

See Also

VSdocman Options