Block comments are sequential comment lines with a header and footer. Below are several examples of a block comments:
----------------------------------
-- Comment
-- Comment
----------------------------------
--================================
-- Comment
-- Comment
--================================
--+-------------------------------
--| Comment
--| Comment
--+-------------------------------
--+---------< header >------------
--| Comment
--| Comment
--+---------< footer >------------
The above examples can be generalized into the following:
--<header_left><header_left_repeat><header_string><header_right_repeat>
--<comment_left>
--<footer_left><footer_left_repeat><footer_string><footer_right_repeat>
Where:
Attribute | Values | Default | Description |
---|---|---|---|
header_left | String None | None | The string to place to the right of the -- |
header_left_repeat | String | - | A character to repeat between header_left and header_string |
header_string | String None | None | A string to place in the header. |
header_right_repeat | String None | None | A character to repeat after the header-string |
comment_left | String None | None | A string which should exist to the right of the -- |
footer_left | String None | None | The string to place to the right of the -- |
footer_left_repeat | String | - | A character to repeat between footer_left and footer_string |
footer_string | String None | None | A string to place in the footer. |
footer_right_repeat | String None | None | A character to repeat after the footer_string |
There are additional options for configuring block comments:
Attribute | Values | Default | Description |
---|---|---|---|
min_height | Integer | 3 | Sets minimum number of consecutive comment lines before being considered a block comment. |
header_alignment | "left" "center" "right" | "center" | Sets horizontal position of header string. |
max_header_column | Integer | 120 | Sets the maximum length of the combined header. |
footer_alignment | "left" "center" "right" | "center" | Sets horizontal position of footer string. |
max_footer_column | Integer | 120 | Sets the maximum length of the combined footer. |
allow_indenting | "yes" "no" | "yes" | Allows indented block comments. Setting this to no will
only detect block comments starting at column 0. |
With these options, a block comment can be validated by VSG.
It is important to note the rules are disabled by default. They must enabled using a configuration.
To configure the following example...
----------------------------------
-- Comment
-- Comment
----------------------------------
...the configuration would be:
rule:
block_comment_001:
disable : False
header_left : ''
header_left_repeat : '-'
header_string : ''
header_right_repeat : ''
block_comment_002:
disable : False
comment_left : ''
block_comment_003:
disable : False
footer_left : ''
footer_left_repeat : '-'
footer_string : ''
footer_right_repeat : ''
To configure the following example...
--+-<Header>==============================
--| Purpose:
--| Author:
--+------------------------------<Footer>=
...the configuration would be:
rule:
block_comment_001:
disable : False
header_left : '+'
header_left_repeat : '-'
header_string : '<Header>'
header_right_repeat : '='
header_alignment : 'left'
block_comment_002:
disable : False
comment_left : '|'
block_comment_003:
disable : False
footer_left : '+'
footer_left_repeat : '-'
footer_string : '<Footer>'
footer_right_repeat : '='
footer_alignment : 'right'
Doxygen comments use an exclamation mark. To configure a block comment for Doxygen...
----------------------------------
--! Comment
--! Comment
----------------------------------
...the configuration would be:
rule:
block_comment_001:
disable : False
header_left : '-'
header_left_repeat : '-'
header_string : ''
header_right_repeat : ''
block_comment_002:
disable : False
comment_left : '!'
block_comment_003:
disable : False
footer_left : '-'
footer_left_repeat : '-'
footer_string : ''
footer_right_repeat : ''