Doc: Developer reference update (#3755)

CHANGES.md

@@ -76,6 +76,9 @@
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+- Updated the _classes_ and _exceptions_ documentation in Developer reference to match
+  the latest ccode base. (#3755)
+
 ## 23.3.0
 
 ### Highlights

docs/contributing/reference/reference_classes.rst

@@ -3,6 +3,9 @@
 
 *Contents are subject to change.*
 
+Black Classes
+~~~~~~~~~~~~~~
+
 .. currentmodule:: black
 
 :class:`BracketTracker`
@@ -18,6 +21,12 @@
     :members:
     :special-members: __str__, __bool__
 
+:class:`RHSResult`
+-------------------------
+
+.. autoclass:: black.lines.RHSResult
+    :members:
+
 :class:`LinesBlock`
 -------------------------
 
@@ -43,6 +52,12 @@
 .. autoclass:: black.comments.ProtoComment
     :members:
 
+:class:`Mode`
+---------------------
+
+.. autoclass:: black.mode.Mode
+    :members:
+
 :class:`Report`
 ---------------
 
@@ -50,6 +65,20 @@
     :members:
     :special-members: __str__
 
+:class:`Ok`
+---------------
+
+.. autoclass:: black.rusty.Ok
+    :show-inheritance:
+    :members:
+
+:class:`Err`
+---------------
+
+.. autoclass:: black.rusty.Err
+    :show-inheritance:
+    :members:
+
 :class:`Visitor`
 ----------------
 
@@ -57,20 +86,115 @@
     :show-inheritance:
     :members:
 
-Enums
+:class:`StringTransformer`
-=====
+----------------------------
+
+.. autoclass:: black.trans.StringTransformer
+    :show-inheritance:
+    :members:
+
+:class:`CustomSplit`
+----------------------------
+
+.. autoclass:: black.trans.CustomSplit
+    :members:
+
+:class:`CustomSplitMapMixin`
+-----------------------------
+
+.. autoclass:: black.trans.CustomSplitMapMixin
+    :show-inheritance:
+    :members:
+
+:class:`StringMerger`
+----------------------
+
+.. autoclass:: black.trans.StringMerger
+    :show-inheritance:
+    :members:
+
+:class:`StringParenStripper`
+-----------------------------
+
+.. autoclass:: black.trans.StringParenStripper
+    :show-inheritance:
+    :members:
+
+:class:`BaseStringSplitter`
+-----------------------------
+
+.. autoclass:: black.trans.BaseStringSplitter
+    :show-inheritance:
+    :members:
+
+:class:`StringSplitter`
+-----------------------------
+
+.. autoclass:: black.trans.StringSplitter
+    :show-inheritance:
+    :members:
+
+:class:`StringParenWrapper`
+-----------------------------
+
+.. autoclass:: black.trans.StringParenWrapper
+    :show-inheritance:
+    :members:
+
+:class:`StringParser`
+-----------------------------
+
+.. autoclass:: black.trans.StringParser
+    :members:
+
+:class:`DebugVisitor`
+------------------------
+
+.. autoclass:: black.debug.DebugVisitor
+    :show-inheritance:
+    :members:
+
+:class:`Replacement`
+------------------------
+
+.. autoclass:: black.handle_ipynb_magics.Replacement
+    :members:
+
+:class:`CellMagic`
+------------------------
+
+.. autoclass:: black.handle_ipynb_magics.CellMagic
+    :members:
+
+:class:`CellMagicFinder`
+------------------------
+
+.. autoclass:: black.handle_ipynb_magics.CellMagicFinder
+    :show-inheritance:
+    :members:
+
+:class:`OffsetAndMagic`
+------------------------
+
+.. autoclass:: black.handle_ipynb_magics.OffsetAndMagic
+    :members:
+
+:class:`MagicFinder`
+------------------------
+
+.. autoclass:: black.handle_ipynb_magics.MagicFinder
+    :show-inheritance:
+    :members:
+
+Enum Classes
+~~~~~~~~~~~~~
+
+Classes inherited from Python `Enum <https://docs.python.org/3/library/enum.html#enum.Enum>`_ class.
 
 :class:`Changed`
 ----------------
 
-.. autoclass:: black.Changed
+.. autoclass:: black.report.Changed
-    :show-inheritance:
-    :members:
-
-:class:`Mode`
------------------
-
-.. autoclass:: black.Mode
     :show-inheritance:
     :members:
 
@@ -80,3 +204,24 @@ Enums
 .. autoclass:: black.WriteBack
     :show-inheritance:
     :members:
+
+:class:`TargetVersion`
+----------------------
+
+.. autoclass:: black.mode.TargetVersion
+    :show-inheritance:
+    :members:
+
+:class:`Feature`
+------------------
+
+.. autoclass:: black.mode.Feature
+    :show-inheritance:
+    :members:
+
+:class:`Preview`
+------------------
+
+.. autoclass:: black.mode.Preview
+    :show-inheritance:
+    :members:

docs/contributing/reference/reference_exceptions.rst

@@ -5,8 +5,14 @@
 
 .. currentmodule:: black
 
+.. autoexception:: black.trans.CannotTransform
+
 .. autoexception:: black.linegen.CannotSplit
 
-.. autoexception:: black.NothingChanged
+.. autoexception:: black.brackets.BracketMatchError
 
-.. autoexception:: black.InvalidInput
+.. autoexception:: black.report.NothingChanged
+
+.. autoexception:: black.parsing.InvalidInput
+
+.. autoexception:: black.mode.Deprecated

docs/contributing/reference/reference_summary.rst

@@ -3,8 +3,11 @@ Developer reference
 
 .. note::
 
-  The documentation here is quite outdated and has been neglected. Many objects worthy
+  As of June 2023, the documentation of *Black classes* and *Black exceptions*
-  of inclusion aren't documented. Contributions are appreciated!
+  has been updated to the latest available version.
+
+  The documentation of *Black functions* is quite outdated and has been neglected. Many
+  functions worthy of inclusion aren't documented. Contributions are appreciated!
 
 *Contents are subject to change.*
 

src/black/handle_ipynb_magics.py

@@ -335,7 +335,8 @@ class CellMagicFinder(ast.NodeVisitor):
 
     For example,
 
-        %%time\nfoo()
+        %%time\n
+        foo()
 
     would have been transformed to
 

src/black/trans.py

@@ -205,11 +205,11 @@ def do_match(self, line: Line) -> TMatchResult:
         """
         Returns:
             * Ok(string_indices) such that for each index, `line.leaves[index]`
-            is our target string if a match was able to be made. For
+              is our target string if a match was able to be made. For
-            transformers that don't result in more lines (e.g. StringMerger,
+              transformers that don't result in more lines (e.g. StringMerger,
-            StringParenStripper), multiple matches and transforms are done at
+              StringParenStripper), multiple matches and transforms are done at
-            once to reduce the complexity.
+              once to reduce the complexity.
-                OR
+              OR
             * Err(CannotTransform), if no match could be made.
         """
 
@@ -220,12 +220,12 @@ def do_transform(
         """
         Yields:
             * Ok(new_line) where new_line is the new transformed line.
-                OR
+              OR
             * Err(CannotTransform) if the transformation failed for some reason. The
-            `do_match(...)` template method should usually be used to reject
+              `do_match(...)` template method should usually be used to reject
-            the form of the given Line, but in some cases it is difficult to
+              the form of the given Line, but in some cases it is difficult to
-            know whether or not a Line meets the StringTransformer's
+              know whether or not a Line meets the StringTransformer's
-            requirements until the transformation is already midway.
+              requirements until the transformation is already midway.
 
         Side Effects:
             This method should NOT mutate @line directly, but it MAY mutate the
@@ -335,8 +335,8 @@ def pop_custom_splits(self, string: str) -> List[CustomSplit]:
 
         Returns:
             * A list of the custom splits that are mapped to @string, if any
-            exist.
+              exist.
-                OR
+              OR
             * [], otherwise.
 
         Side Effects:
@@ -365,14 +365,14 @@ class StringMerger(StringTransformer, CustomSplitMapMixin):
     Requirements:
         (A) The line contains adjacent strings such that ALL of the validation checks
         listed in StringMerger._validate_msg(...)'s docstring pass.
-            OR
+        OR
         (B) The line contains a string which uses line continuation backslashes.
 
     Transformations:
         Depending on which of the two requirements above where met, either:
 
         (A) The string group associated with the target string is merged.
-            OR
+        OR
         (B) All line-continuation backslashes are removed from the target string.
 
     Collaborations:
@@ -965,17 +965,20 @@ class BaseStringSplitter(StringTransformer):
 
     Requirements:
         * The target string value is responsible for the line going over the
-        line length limit. It follows that after all of black's other line
+          line length limit. It follows that after all of black's other line
-        split methods have been exhausted, this line (or one of the resulting
+          split methods have been exhausted, this line (or one of the resulting
-        lines after all line splits are performed) would still be over the
+          lines after all line splits are performed) would still be over the
-        line_length limit unless we split this string.
+          line_length limit unless we split this string.
-            AND
+          AND
+
         * The target string is NOT a "pointless" string (i.e. a string that has
-        no parent or siblings).
+          no parent or siblings).
-            AND
+          AND
+
         * The target string is not followed by an inline comment that appears
-        to be a pragma.
+          to be a pragma.
-            AND
+          AND
+
         * The target string is not a multiline (i.e. triple-quote) string.
     """
 
@@ -1027,7 +1030,7 @@ def _validate(self, line: Line, string_idx: int) -> TResult[None]:
 
         Returns:
             * Ok(None), if ALL of the requirements are met.
-                OR
+              OR
             * Err(CannotTransform), if ANY of the requirements are NOT met.
         """
         LL = line.leaves
@@ -1299,9 +1302,9 @@ class StringSplitter(BaseStringSplitter, CustomSplitMapMixin):
 
     Requirements:
         * The line consists ONLY of a single string (possibly prefixed by a
-        string operator [e.g. '+' or '==']), MAYBE a string trailer, and MAYBE
+          string operator [e.g. '+' or '==']), MAYBE a string trailer, and MAYBE
-        a trailing comma.
+          a trailing comma.
-            AND
+          AND
         * All of the requirements listed in BaseStringSplitter's docstring.
 
     Transformations:
@@ -1808,26 +1811,26 @@ class StringParenWrapper(BaseStringSplitter, CustomSplitMapMixin):
         addition to the requirements listed below:
 
         * The line is a return/yield statement, which returns/yields a string.
-            OR
+          OR
         * The line is part of a ternary expression (e.g. `x = y if cond else
-        z`) such that the line starts with `else <string>`, where <string> is
+          z`) such that the line starts with `else <string>`, where <string> is
-        some string.
+          some string.
-            OR
+          OR
         * The line is an assert statement, which ends with a string.
-            OR
+          OR
         * The line is an assignment statement (e.g. `x = <string>` or `x +=
-        <string>`) such that the variable is being assigned the value of some
+          <string>`) such that the variable is being assigned the value of some
-        string.
+          string.
-            OR
+          OR
         * The line is a dictionary key assignment where some valid key is being
-        assigned the value of some string.
+          assigned the value of some string.
-            OR
+          OR
         * The line is an lambda expression and the value is a string.
-            OR
+          OR
         * The line starts with an "atom" string that prefers to be wrapped in
-        parens. It's preferred to be wrapped when it's is an immediate child of
+          parens. It's preferred to be wrapped when it's is an immediate child of
-        a list/set/tuple literal, AND the string is surrounded by commas (or is
+          a list/set/tuple literal, AND the string is surrounded by commas (or is
-        the first/last child).
+          the first/last child).
 
     Transformations:
         The chosen string is wrapped in parentheses and then split at the LPAR.
@@ -2273,7 +2276,7 @@ def parse(self, leaves: List[Leaf], string_idx: int) -> int:
         Returns:
             The index directly after the last leaf which is apart of the string
             trailer, if a "trailer" exists.
-                OR
+            OR
             @string_idx + 1, if no string "trailer" exists.
         """
         assert leaves[string_idx].type == token.STRING
@@ -2287,11 +2290,11 @@ def _next_state(self, leaf: Leaf) -> bool:
         """
         Pre-conditions:
             * On the first call to this function, @leaf MUST be the leaf that
-            was directly after the string leaf in question (e.g. if our target
+              was directly after the string leaf in question (e.g. if our target
-            string is `line.leaves[i]` then the first call to this method must
+              string is `line.leaves[i]` then the first call to this method must
-            be `line.leaves[i + 1]`).
+              be `line.leaves[i + 1]`).
             * On the next call to this function, the leaf parameter passed in
-            MUST be the leaf directly following @leaf.
+              MUST be the leaf directly following @leaf.
 
         Returns:
             True iff @leaf is apart of the string's trailer.