Merge pull request matplotlib#29303 from timhoffm/doc-discouraged

DOC: Enhance documentation on discouraged API

Author: QuLogic

doc/devel/api_changes.rst

@@ -256,3 +256,8 @@ To do so, add a note to the docstring ::
 
 You find several examples for good descriptions if you search the codebase for
 ``.. admonition:: Discouraged``.
+
+Additionally, if a whole function is discouraged, prefix the summary line with
+``[*Discouraged*]`` so that it renders in the API overview like this
+
+    [*Discouraged*] Return the XAxis instance.