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
-    :show-inheritance:
-    :members:
-
-:class:`Mode`
------------------
-
-.. autoclass:: black.Mode
+.. autoclass:: black.report.Changed
     :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
-  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/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

@@ -970,12 +970,15 @@ class BaseStringSplitter(StringTransformer):
           lines after all line splits are performed) would still be over the
           line_length limit unless we split this string.
           AND
+
         * The target string is NOT a "pointless" string (i.e. a string that has
           no parent or siblings).
           AND
+
         * The target string is not followed by an inline comment that appears
           to be a pragma.
           AND
+
         * The target string is not a multiline (i.e. triple-quote) string.
     """