Resurrection of the comment filter

docsite/rst/playbooks_filters.rst

@@ -352,6 +352,73 @@ override those in `b`, and so on.
 This behaviour does not depend on the value of the `hash_behaviour`
 setting in `ansible.cfg`.
 
+.. _comment_filter:
+
+Comment Filter
+--------------
+
+.. versionadded:: 2.0
+
+The `comment` filter allows to decorate the text with a chosen comment
+style. For example the following::
+
+    {{ "Plain style (default)" | comment }}
+
+will produce the this output::
+
+    #
+    # Plain style (default)
+    #
+
+Similar way can be applied style for C (``//...``), C block
+(``/*...*/``), Erlang (``%...``) and XML (``<!--...-->``)::
+
+    {{ "C style" | comment('c') }}
+    {{ "C block style" | comment('cblock') }}
+    {{ "Erlang style" | comment('erlang') }}
+    {{ "XML style" | comment('xml') }}
+
+It is also possible to fully customize the comment style::
+
+    {{ "Custom style" | comment('plain', prefix='#######\n#', postfix='#\n#######\n   ###\n    #') }}
+
+That will create the following output::
+
+    #######
+    #
+    # Custom style
+    #
+    #######
+       ###
+        #
+
+The filter can also be applied to any Ansible variable. For example to
+make the output of the ``ansible_managed`` variable more readable, we can
+change the definition in the ``ansible.cfg`` file to this::
+
+    [defaults]
+
+    ansible_managed = This file is managed by Ansible.%n
+      template: {file}
+      date: %Y-%m-%d %H:%M:%S
+      user: {uid}
+      host: {host}
+
+and then use the variable with the `comment` filter::
+
+    {{ ansible_managed | comment }}
+
+which will produce this output::
+
+    #
+    # This file is managed by Ansible.
+    #
+    # template: /home/ansible/env/dev/ansible_managed/roles/role1/templates/test.j2
+    # date: 2015-09-10 11:02:58
+    # user: ansible
+    # host: myhost
+    #
+
 .. _other_useful_filters:
 
 Other Useful Filters