Updates to slsutil.banner

salt/modules/slsutil.py

@@ -279,13 +279,11 @@ def banner(width=72, commentchar='#', borderchar='#', blockstart=None, blockend=
     :param newline: Boolean value to indicate whether the comment block should
         end with a newline. Default is ``False``.
 
-    This banner can be injected into any templated file, for example:
+    **Example 1 - the default banner:**
 
     .. code-block:: jinja
 
-        {{ salt['slsutil.banner'](width=120, commentchar='//') }}
-
-    The default banner:
+        {{ salt['slsutil.banner']() }}
 
     .. code-block:: none
 
@@ -296,6 +294,42 @@ def banner(width=72, commentchar='#', borderchar='#', blockstart=None, blockend=
         # The contents of this file are managed by Salt. Any changes to this   #
         # file may be overwritten automatically and without warning.           #
         ########################################################################
+
+    **Example 2 - a Javadoc-style banner:**
+
+    .. code-block:: jinja
+
+        {{ salt['slsutil.banner'](commentchar=' *', borderchar='*', blockstart='/**', blockend=' */') }}
+
+    .. code-block:: none
+
+        /**
+         ***********************************************************************
+         *                                                                     *
+         *              THIS FILE IS MANAGED BY SALT - DO NOT EDIT             *
+         *                                                                     *
+         * The contents of this file are managed by Salt. Any changes to this  *
+         * file may be overwritten automatically and without warning.          *
+         ***********************************************************************
+         */
+
+    **Example 3 - custom text:**
+
+    .. code-block:: jinja
+
+        {{ set copyright='This file may not be copied or distributed without the express permission of ACME Corp.' }}
+        {{ salt['slsutil.banner'](title='Copyright 2019 ACME Corp', text=copyright) }}
+
+    .. code-block:: none
+
+        ########################################################################
+        #                                                                      #
+        #                       Copyright 2019 ACME Corp                       #
+        #                                                                      #
+        # This file may not be copied or distributed without the express       #
+        # permission of ACME Corp.                                             #
+        ########################################################################
+
     '''
 
     if title is None:
@@ -304,18 +338,26 @@ def banner(width=72, commentchar='#', borderchar='#', blockstart=None, blockend=
     if text is None:
         text = ('The contents of this file are managed by Salt. '
                 'Any changes to this file may be overwritten '
-                'automatically and without warning')
+                'automatically and without warning.')
 
     # Set up some typesetting variables
-    lgutter = commentchar.strip() + ' '
-    rgutter = ' ' + commentchar.strip()
+    ledge = commentchar.rstrip()
+    redge = commentchar.strip()
+    lgutter = ledge + ' '
+    rgutter = ' ' + redge
     textwidth = width - len(lgutter) - len(rgutter)
-    border_line = commentchar + borderchar[:1] * (width - len(commentchar) * 2) + commentchar
+
+    # Check the width
+    if textwidth <= 0:
+        raise salt.exceptions.ArgumentValueError('Width is too small to render banner')
+
+    # Define the static elements
+    border_line = commentchar + borderchar[:1] * (width - len(ledge) - len(redge)) + redge
     spacer_line = commentchar + ' ' * (width - len(commentchar) * 2) + commentchar
-    wrapper = textwrap.TextWrapper(width=(width - len(lgutter) - len(rgutter)))
-    block = list()
 
     # Create the banner
+    wrapper = textwrap.TextWrapper(width=textwidth)
+    block = list()
     if blockstart is not None:
         block.append(blockstart)
     block.append(border_line)

tests/unit/modules/test_slsutil.py

@@ -32,6 +32,7 @@ def test_banner(self):
         self.check_banner(width=20)
         self.check_banner(commentchar='//', borderchar='-')
         self.check_banner(title='title here', text='text here')
+        self.check_banner(commentchar=' *')
 
     def check_banner(self, width=72, commentchar='#', borderchar='#', blockstart=None, blockend=None,
                      title=None, text=None, newline=True):
@@ -42,7 +43,7 @@ def check_banner(self, width=72, commentchar='#', borderchar='#', blockstart=Non
         for line in result:
             self.assertEqual(len(line), width)
             self.assertTrue(line.startswith(commentchar))
-            self.assertTrue(line.endswith(commentchar))
+            self.assertTrue(line.endswith(commentchar.strip()))
 
     def test_boolstr(self):
         '''