Configuring Block Comments

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

Block Comment Structure

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 Boolean True Allows indented block comments. Setting this to False will only detect block comments starting at column 0.

With these options, a block comment can be validated by VSG.

Examples

It is important to note the rules are disabled by default. They must enabled using a configuration.

Simple Block Comment

To configure the following example…

----------------------------------
-- Comment
-- Comment
----------------------------------

…the configuration would be:

rule:
  block_comment_001:
    disable : False
    header_left : None
    header_left_repeat : '-'
    header_string : None
    header_right_repeat : None
  block_comment_002:
    disable : False
    comment_left : None
  block_comment_003:
    disable : False
    footer_left : None
    footer_left_repeat : '-'
    footer_string : None
    footer_right_repeat : None

Complex Block Comment

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 Block Comment

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 : None
    header_right_repeat : None
  block_comment_002:
    disable : False
    comment_left : '!'
  block_comment_003:
    disable : False
    footer_left : '-'
    footer_left_repeat : '-'
    footer_string : None
    footer_right_repeat : None