Docs: Replace notes with real '.. deprecated' markup

ferdnyc · ptmcg · commit 9efe96d0bc87 · 2025-06-26T00:25:57.000-05:00
diff --git a/pyparsing/core.py b/pyparsing/core.py
@@ -1979,7 +1979,11 @@ def _checkRecursion(self, parseElementList):
 
     def validate(self, validateTrace=None) -> None:
         """
+        .. deprecated:: 3.0.0
+           Do not use to check for left recursion.
+
         Check defined expressions for valid structure, check for infinite recursive definitions.
+
         """
         warnings.warn(
             "ParserElement.validate() is deprecated, and should not be used to check for left recursion",
diff --git a/pyparsing/exceptions.py b/pyparsing/exceptions.py
@@ -299,11 +299,12 @@ class ParseSyntaxException(ParseFatalException):
 
 class RecursiveGrammarException(Exception):
     """
+    .. deprecated:: 3.0.0
+       Only used by the deprecated :meth:`ParserElement.validate`.
+
     Exception thrown by :class:`ParserElement.validate` if the
     grammar could be left-recursive; parser may need to enable
     left recursion using :class:`ParserElement.enable_left_recursion<ParserElement.enable_left_recursion>`
-
-    Deprecated: only used by deprecated method ParserElement.validate.
     """
 
     def __init__(self, parseElementList) -> None:
diff --git a/pyparsing/helpers.py b/pyparsing/helpers.py
@@ -385,7 +385,9 @@ def ungroup(expr: ParserElement) -> ParserElement:
 
 def locatedExpr(expr: ParserElement) -> ParserElement:
     """
-    (DEPRECATED - future code should use the :class:`Located` class)
+    .. deprecated:: 3.0.0
+       Use the :class:`Located` class instead.
+
     Helper to decorate a returned token with its starting and ending
     locations in the input string.
 
@@ -914,7 +916,9 @@ def parseImpl(self, instring, loc, doActions=True):
 
 def indentedBlock(blockStatementExpr, indentStack, indent=True, backup_stacks=[]):
     """
-    (DEPRECATED - use :class:`IndentedBlock` class instead)
+    .. deprecated:: 3.0.0
+       Use the :class:`IndentedBlock` class instead.
+
     Helper method for defining space-delimited indentation blocks,
     such as those used to define block statements in Python source code.
 
@@ -1096,7 +1100,10 @@ def delimited_list(
     *,
     allow_trailing_delim: bool = False,
 ) -> ParserElement:
-    """(DEPRECATED - use :class:`DelimitedList` class)"""
+    """
+    .. deprecated:: 3.1.0
+       Use the :class:`DelimitedList` class instead.
+    """
     return DelimitedList(
         expr, delim, combine, min, max, allow_trailing_delim=allow_trailing_delim
     )
diff --git a/pyparsing/results.py b/pyparsing/results.py
@@ -804,12 +804,17 @@ def is_iterable(obj):
             ret = cls([ret], name=name)
         return ret
 
+    # XXX: These docstrings don't show up in the documentation
+    #      (asList.__doc__ is the same as as_list.__doc__)
     asList = as_list
-    """Deprecated - use :class:`as_list`"""
+    """.. deprecated:: 3.0.0
+          use :class:`as_list`"""
     asDict = as_dict
-    """Deprecated - use :class:`as_dict`"""
+    """.. deprecated:: 3.0.0
+          use :class:`as_dict`"""
     getName = get_name
-    """Deprecated - use :class:`get_name`"""
+    """.. deprecated:: 3.0.0
+          use :class:`get_name`"""
 
 
 MutableMapping.register(ParseResults)
diff --git a/pyparsing/util.py b/pyparsing/util.py
@@ -425,7 +425,10 @@ def _inner(*args, **kwargs):
             # )
             return fn(*args, **kwargs)
 
-    _inner.__doc__ = f"""Deprecated - use :class:`{fn.__name__}`"""
+    _inner.__doc__ = f"""
+        .. deprecated:: 3.0.0
+           Use :class:`{fn.__name__}` instead
+        """
     _inner.__name__ = compat_name
     _inner.__annotations__ = fn.__annotations__
     if isinstance(fn, types.FunctionType):
