Clarify deprecation of "async" parameter

For vendor passthru decorators, the "async" parameter is deprecated.
This clarifies the messaging we emit (via logs and release notes), and
adds a TODO so we don't forget to delete the "async" parameter in
Stein cycle.

This is a follow up to Change-Id: I6299aafd30faae9a93df2cb901c1505df47e6b45.

Change-Id: I63ddf453584f4e7e8d2fa778ec50b8debcb86bf4
Task: 9289
Story: 1751306

ironic/drivers/base.py

@@ -655,11 +655,15 @@ def _passthru(http_methods, method=None, async=None, async_call=None,
                                    for a synchronous passthru method. If False,
                                    don't lock the node. Defaults to True.
     """
+    # TODO(rloo): In Stein cycle, remove support for 'async' parameter.
+    #             The default value for 'async_call' should then be changed
+    #             to True.
     if async_call is None:
         if async is not None:
             LOG.warning(
-                'async parameter is deprecated, please use async_call instead.'
-                'deprecated parameter will be removed in the next cycle.'
+                'The "async" parameter is deprecated, please use "async_call" '
+                'instead. The "async" parameter will be removed in the Stein '
+                'cycle.'
             )
             async_call = async
         else:
@@ -667,8 +671,9 @@ def _passthru(http_methods, method=None, async=None, async_call=None,
     else:
         if async is not None:
             raise TypeError(
-                "async_call and async parameters couldn't be used together, "
-                "use async_call instead of async"
+                "'async_call' and 'async' parameters cannot be used together. "
+                "Use 'async_call' instead of 'async' since 'async' is "
+                "deprecated and will be removed in the Stein cycle."
             )
 
     def handle_passthru(func):

releasenotes/notes/async-deprecate-b3d81d7968ea47e5.yaml

@@ -1,4 +1,9 @@
 ---
 other:
-    async parameter of passthru and driver_passthru decorators is deprecated
-    and will be removed in next cycle. async_call should be used instead.
+    For out-of-tree drivers that have `vendor passthru methods
+    <https://docs.openstack.org/ironic/latest/contributor/vendor-passthru.html>`_.
+    The ``async`` parameter of the ``passthru`` and ``driver_passthru``
+    decorators is deprecated and will be removed in the Stein cycle.
+    Please use its replacement instead, the ``async_call`` parameter.
+    For more information, see `bug 1751306
+    <https://storyboard.openstack.org/#!/story/1751306>`_.