more fixing & changes.md

CHANGES.md

@@ -74,6 +74,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

@@ -65,6 +65,20 @@ Black Classes
     :members:
     :special-members: __str__
 
+:class:`Ok`
+---------------
+
+.. autoclass:: black.rusty.Ok
+    :show-inheritance:
+    :members:
+
+:class:`Err`
+---------------
+
+.. autoclass:: black.rusty.Err
+    :show-inheritance:
+    :members:
+
 :class:`Visitor`
 ----------------
 
@@ -79,6 +93,12 @@ Black Classes
     :show-inheritance:
     :members:
 
+:class:`CustomSplit`
+----------------------------
+
+.. autoclass:: black.trans.CustomSplit
+    :members:
+
 :class:`CustomSplitMapMixin`
 -----------------------------
 
@@ -107,13 +127,39 @@ Black Classes
     :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`
 ------------------------
 
@@ -127,6 +173,12 @@ Black Classes
     :show-inheritance:
     :members:
 
+:class:`OffsetAndMagic`
+------------------------
+
+.. autoclass:: black.handle_ipynb_magics.OffsetAndMagic
+    :members:
+
 :class:`MagicFinder`
 ------------------------
 
@@ -142,11 +194,10 @@ Classes inherited from Python `Enum <https://docs.python.org/3/library/enum.html
 :class:`Changed`
 ----------------
 
-.. autoclass:: black.Changed
+.. autoclass:: black.report.Changed
     :show-inheritance:
     :members:
 
-
 :class:`WriteBack`
 ------------------
 
@@ -157,14 +208,14 @@ Classes inherited from Python `Enum <https://docs.python.org/3/library/enum.html
 :class:`TargetVersion`
 ----------------------
 
-.. autoclass:: black.TargetVersion
+.. autoclass:: black.mode.TargetVersion
     :show-inheritance:
     :members:
 
 :class:`Feature`
 ------------------
 
-.. autoclass:: black.Feature
+.. autoclass:: black.mode.Feature
     :show-inheritance:
     :members:
 

docs/contributing/reference/reference_exceptions.rst

@@ -11,8 +11,8 @@
 
 .. autoexception:: black.brackets.BracketMatchError
 
-.. autoexception:: black.NothingChanged
+.. autoexception:: black.report.NothingChanged
 
-.. autoexception:: black.InvalidInput
+.. 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
-  of inclusion aren't documented. Contributions are appreciated!
+  As of June 2023, the documentation of *Black classes* and *Black exceptions*
+  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/trans.py

@@ -1302,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
-        a trailing comma.
-            AND
+          string operator [e.g. '+' or '==']), MAYBE a string trailer, and MAYBE
+          a trailing comma.
+          AND
         * All of the requirements listed in BaseStringSplitter's docstring.
 
     Transformations:
@@ -1811,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
-        some string.
-            OR
+          z`) such that the line starts with `else <string>`, where <string> is
+          some string.
+          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.
-            OR
+          <string>`) such that the variable is being assigned the value of some
+          string.
+          OR
         * The line is a dictionary key assignment where some valid key is being
-        assigned the value of some string.
-            OR
+          assigned the value of some string.
+          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
-        a list/set/tuple literal, AND the string is surrounded by commas (or is
-        the first/last child).
+          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
+          the first/last child).
 
     Transformations:
         The chosen string is wrapped in parentheses and then split at the LPAR.
@@ -2276,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
@@ -2290,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
-            string is `line.leaves[i]` then the first call to this method must
-            be `line.leaves[i + 1]`).
+              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
+              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.