From 3cb4e76175c06370cc7b69a326c9ae1c6c0b0c37 Mon Sep 17 00:00:00 2001
From: Darko Poljak <foss@ungleich.com>
Date: Wed, 19 Jun 2019 18:19:32 +0200
Subject: [PATCH] Allow custom message for each deprecated parameter

---
 cdist/config.py                               | 11 +++++--
 cdist/core/cdist_type.py                      | 24 +++++++-------
 cdist/test/cdist_type/__init__.py             |  9 ++++--
 .../parameter/deprecated                      |  2 --
 .../parameter/deprecated/eggs                 |  1 +
 .../{deprecated => parameter/deprecated/spam} |  0
 .../parameter/optional                        |  1 -
 docs/src/cdist-type.rst                       | 31 ++++++++++---------
 8 files changed, 44 insertions(+), 35 deletions(-)
 delete mode 100644 cdist/test/cdist_type/fixtures/__with_deprecated_parameters/parameter/deprecated
 create mode 100644 cdist/test/cdist_type/fixtures/__with_deprecated_parameters/parameter/deprecated/eggs
 rename cdist/test/cdist_type/fixtures/__with_deprecated_parameters/{deprecated => parameter/deprecated/spam} (100%)

diff --git a/cdist/config.py b/cdist/config.py
index 6622823b..26d07fc4 100644
--- a/cdist/config.py
+++ b/cdist/config.py
@@ -769,9 +769,14 @@ class Config(object):
                 self.log.warning("Type %s is deprecated.", cdist_type.name)
         for param in cdist_object.parameters:
             if param in cdist_type.deprecated_parameters:
-                self.log.warning(("%s parameter of type %s is deprecated, "
-                                  "see man page for details"),
-                                 param, cdist_type.name)
+                msg = cdist_type.deprecated_parameters[param]
+                if msg:
+                    format = "%s parameter of type %s is deprecated: %s"
+                    args = [param, cdist_type.name, msg]
+                else:
+                    format = "%s parameter of type %s is deprecated."
+                    args = [param, cdist_type.name]
+                self.log.warning(format, *args)
 
     def object_prepare(self, cdist_object, transfer_type_explorers=True):
         """Prepare object: Run type explorer + manifest"""
diff --git a/cdist/core/cdist_type.py b/cdist/core/cdist_type.py
index 48926a03..4500f50d 100644
--- a/cdist/core/cdist_type.py
+++ b/cdist/core/cdist_type.py
@@ -279,20 +279,20 @@ class CdistType(object):
 
     @property
     def deprecated_parameters(self):
-        """Return a list of deprecated parameters"""
         if not self.__deprecated_parameters:
-            parameters = []
+            deprecated = {}
             try:
-                with open(os.path.join(self.absolute_path,
-                                       "parameter",
-                                       "deprecated")) as fd:
-                    for line in fd:
-                        line = line.strip()
-                        if line:
-                            parameters.append(line)
+                deprecated_dir = os.path.join(self.absolute_path,
+                                              "parameter",
+                                              "deprecated")
+                for name in cdist.core.listdir(deprecated_dir):
+                    try:
+                        with open(os.path.join(deprecated_dir, name)) as fd:
+                            deprecated[name] = fd.read().strip()
+                    except EnvironmentError:
+                        pass  # Swallow errors raised by open() or read()
             except EnvironmentError:
-                # error ignored
-                pass
+                pass  # Swallow error raised by os.listdir()
             finally:
-                self.__deprecated_parameters = parameters
+                self.__deprecated_parameters = deprecated
         return self.__deprecated_parameters
diff --git a/cdist/test/cdist_type/__init__.py b/cdist/test/cdist_type/__init__.py
index 9eee395c..a51a1e6f 100644
--- a/cdist/test/cdist_type/__init__.py
+++ b/cdist/test/cdist_type/__init__.py
@@ -205,10 +205,13 @@ class TypeTestCase(test.CdistTestCase):
         base_path = fixtures
         cdist_type = core.CdistType(base_path,
                                     '__without_deprecated_parameters')
-        self.assertEqual(cdist_type.deprecated_parameters, [])
+        self.assertEqual(cdist_type.deprecated_parameters, {})
 
     def test_with_deprecated_parameters(self):
         base_path = fixtures
         cdist_type = core.CdistType(base_path, '__with_deprecated_parameters')
-        self.assertEqual(cdist_type.deprecated_parameters,
-                         ['eggs', 'spam'])
+        self.assertTrue('eggs' in cdist_type.deprecated_parameters)
+        self.assertTrue('spam' in cdist_type.deprecated_parameters)
+        self.assertEqual(cdist_type.deprecated_parameters['eggs'],
+                         'Deprecated')
+        self.assertEqual(cdist_type.deprecated_parameters['spam'], '')
diff --git a/cdist/test/cdist_type/fixtures/__with_deprecated_parameters/parameter/deprecated b/cdist/test/cdist_type/fixtures/__with_deprecated_parameters/parameter/deprecated
deleted file mode 100644
index 81830edb..00000000
--- a/cdist/test/cdist_type/fixtures/__with_deprecated_parameters/parameter/deprecated
+++ /dev/null
@@ -1,2 +0,0 @@
-eggs
-spam
diff --git a/cdist/test/cdist_type/fixtures/__with_deprecated_parameters/parameter/deprecated/eggs b/cdist/test/cdist_type/fixtures/__with_deprecated_parameters/parameter/deprecated/eggs
new file mode 100644
index 00000000..69d9f456
--- /dev/null
+++ b/cdist/test/cdist_type/fixtures/__with_deprecated_parameters/parameter/deprecated/eggs
@@ -0,0 +1 @@
+Deprecated
diff --git a/cdist/test/cdist_type/fixtures/__with_deprecated_parameters/deprecated b/cdist/test/cdist_type/fixtures/__with_deprecated_parameters/parameter/deprecated/spam
similarity index 100%
rename from cdist/test/cdist_type/fixtures/__with_deprecated_parameters/deprecated
rename to cdist/test/cdist_type/fixtures/__with_deprecated_parameters/parameter/deprecated/spam
diff --git a/cdist/test/cdist_type/fixtures/__with_deprecated_parameters/parameter/optional b/cdist/test/cdist_type/fixtures/__with_deprecated_parameters/parameter/optional
index 7c804d5f..bfe09199 100644
--- a/cdist/test/cdist_type/fixtures/__with_deprecated_parameters/parameter/optional
+++ b/cdist/test/cdist_type/fixtures/__with_deprecated_parameters/parameter/optional
@@ -1,4 +1,3 @@
 spam
 eggs
 sausage
-spam
diff --git a/docs/src/cdist-type.rst b/docs/src/cdist-type.rst
index 623ba481..582c0938 100644
--- a/docs/src/cdist-type.rst
+++ b/docs/src/cdist-type.rst
@@ -188,24 +188,27 @@ Example: (e.g. in cdist/conf/type/__nginx_vhost/manifest)
 
 Deprecated parameters
 ---------------------
-To deprecate type parameters one can declare a newline separated file
-**parameter/deprecated** where each line contains deprecated parameter.
-When it is used cdist writes warning line, e.g.:
+To deprecate type parameters one can declare a file for each deprecated
+parameter under **parameter/deprecated** directory.
+
+When such parameter is used cdist writes warning line with deprecation message.
+If such file has content then this content is printed as deprecation message.
+If there is no content then generic parameter deprecation message is printed.
+
+Example:
 
 .. code-block:: sh
 
-    $ cat parameter/optional_multiple
-    foo
-    spam
-    eggs
-    $ cat parameter/deprecated
-    spam
-    eggs
-    $ echo '__foo foo --foo foo --spam spam' | ./bin/cdist config -i - 185.203.112.26
-    WARNING: 185.203.112.26: spam parameter of type __foo is deprecated, see man page for details
+    $ ls parameter/deprecated/
+    eggs    spam
+    $ cat parameter/deprecated/eggs
+    eggs parameter is deprecated, please use multiple egg parameter.
+    $ cat parameter/deprecated/spam
+    $ echo '__foo foo --foo foo --eggs eggs' | ./bin/cdist config -i - 185.203.112.26
+    WARNING: 185.203.112.26: eggs parameter of type __foo is deprecated: eggs parameter is deprecated, please use multiple egg parameter.
     $ echo '__foo foo --foo foo --eggs eggs --spam spam' | ./bin/cdist config -i - 185.203.112.26
-    WARNING: 185.203.112.26: spam parameter of type __foo is deprecated, see man page for details
-    WARNING: 185.203.112.26: eggs parameter of type __foo is deprecated, see man page for details
+    WARNING: 185.203.112.26: spam parameter of type __foo is deprecated.
+    WARNING: 185.203.112.26: eggs parameter of type __foo is deprecated: eggs parameter is deprecated, please use multiple egg parameter.
 
 
 Input from stdin