Rename "extra_info" to "optional_info"

Feels a bit clearer to me.

Author: lagru

docs/typing_syntax.md

@@ -16,13 +16,13 @@ Docstrings should follow a form that is inspired by the NumPyDoc style:
 ```
 Section name
 ------------
-name : doctype, extra_info
+name : doctype, optional_info
   Description.
 ```
 
 - `name` might be the name of a parameter, attribute or similar.
 - `doctype` the actual type information that will be transformed into a Python type.
-- `extra_info` is optional and captures anything after the first comma (that is not inside a type expression).
+- `optional_info` is optional and captures anything after the first comma (that is not inside a type expression).
   It is useful to provide additional information for readers.
   Its presence and content doesn't currently affect the resulting type annotation.
 

src/docstub/_docstrings.py

@@ -474,7 +474,7 @@ def optional(self, tree):
         logger.debug("dropping optional / default info")
         return lark.Discard
 
-    def extra_info(self, tree):
+    def optional_info(self, tree):
         """
         Parameters
         ----------
@@ -484,7 +484,7 @@ def extra_info(self, tree):
         -------
         out : lark.visitors._DiscardType
         """
-        logger.debug("dropping extra info")
+        logger.debug("dropping optional info")
         return lark.Discard
 
     def __default__(self, data, children, meta):

src/docstub/doctype.lark

@@ -12,7 +12,7 @@
 // The basic structure of a full docstring annotation as it comes after the
 // `name : `. It includes additional meta information that is optional and
 // currently ignored.
-?annotation_with_meta: type ("," extra_info)?
+?annotation_with_meta: type ("," optional_info)?
 
 
 // A type annotation. Can range from a simple qualified name to a complex
@@ -132,9 +132,10 @@ shape: "(" dim ",)"
 ?dim: INT | ELLIPSES | NAME ("=" INT)?
 
 
-// Extra meta information added after the docstring annotation, e.g. "optional"
-// or "default: 3". Information is dropped and not used to generate stubs.
-extra_info: /[^\r\n]+/
+// Optional meta information added after the docstring annotation, e.g.
+// "optional" or "in range (0, 10), default: 3". Information is dropped and not
+// used to generate stubs.
+optional_info: /[^\r\n]+/
 
 // A simple name. Can start with a number or character. Can be delimited by "_"
 // or "-" but not by ".".

tests/test_docstrings.py

@@ -143,7 +143,7 @@ def test_literals(self, doctype, expected):
         ],
     )
     @pytest.mark.parametrize(
-        "extra_info",
+        "optional_info",
         [
             "",
             ", optional",
@@ -155,10 +155,10 @@ def test_literals(self, doctype, expected):
             ", see parameter `image`, optional",
         ],
     )
-    def test_extra_info(self, doctype, expected, extra_info):
-        doctype_with_extra = doctype + extra_info
+    def test_optional_info(self, doctype, expected, optional_info):
+        doctype_with_optional = doctype + optional_info
         transformer = DoctypeTransformer()
-        annotation, _ = transformer.doctype_to_annotation(doctype_with_extra)
+        annotation, _ = transformer.doctype_to_annotation(doctype_with_optional)
         assert annotation.value == expected
 
     @pytest.mark.parametrize(