Comment rule defines XML comment for particular elements. The rule consists of conditions and XML comment. The conditions usually test element name and type. The comment from rule is applied if specified conditions are true. Rules are part of comment templates. One template may contain any number of rules. They are sorted by priority and the first rule with true condition is applied.

To edit the rule, go to Tools - VSdocman menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Options pane. Set element type under Comment Templates. Select any rule from the list and press Edit or press Add button.

Rule name

Rule name has no meaning and only serves for better orientation in a list of rules.

Conditions

Depending on an element type, there are one or two conditions. Each element type has condition that tests its name (except constructors). Some elements also test the return or value type.

The condition format is very simple. It is a standard regular expression that the input must match. You can use full regex syntax supported by .NET framework. In addition, if you want to allow any value, you don't need to use .* but you can leave the field blank. Don't forget to escape special characters like dot, comma or parentheses with \.

Name condition

This condition tests the element's name. This is full name including namespace and class. But the name doesn't contain parameters. So if you want to match the "Finalize" method, you need to match anything before last dot and then "Finalize" string. So the regex is ".*\.Finalize". You will probably start each name condition with ".*\.". If the input contains newlines, then .* stops on the next newline. To search over newlines, use (.|\n)* instead.

Type condition

This condition tests the element's type or return type. This is a full name including namespace and class. So if you want to match the "bool" type, your regex needs to be "System\.Boolean".

Test buttons

The Test button opens quick regex tester where you can immediately see whether your pattern works as expected. You can even edit the pattern and apply it to edited rule.

Regular expressions tester and editor

XML Comment

This is XML comment that will be used if the rule is applied. To allow maximum flexibility, you can use macros in the comment definition. See the list of macros available in comment templates. For example, $DECLARING-TYPE-NAME$ macro is set to the name of declaring class/interface. You can insert macros easily using Insert Macro button.

See Also