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

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

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

Rules Enforcing Block Comments

• block_comment_001

• block_comment_002

• block_comment_003