From: Autophagy <mika@crate.io>
Date: Fri, 8 May 2020 13:41:27 +0000 (+0200)
Subject: Add docstrings to fmt checking functions, add to docs
X-Git-Url: https://git.madduck.net/etc/vim.git/commitdiff_plain/ede23ae7ff7056cd207398578588d37b386d4d76?ds=sidebyside;hp=c0a7582e3d4cc8bec3b7f5a6c52b36880dcb57d7

Add docstrings to fmt checking functions, add to docs

Follow up from #1325

Adds docstrings to the fmt checking functions.
Renames fmt_on to is_fmt_on.
Adds the functions to the autodocs.
---

diff --git a/black.py b/black.py
index fc1597a..2b718f6 100644
--- a/black.py
+++ b/black.py
@@ -5232,7 +5232,7 @@ def generate_ignored_nodes(leaf: Leaf) -> Iterator[LN]:
     """
     container: Optional[LN] = container_of(leaf)
     while container is not None and container.type != token.ENDMARKER:
-        if fmt_on(container):
+        if is_fmt_on(container):
             return
 
         # fix for fmt: on in children
@@ -5246,17 +5246,21 @@ def generate_ignored_nodes(leaf: Leaf) -> Iterator[LN]:
             container = container.next_sibling
 
 
-def fmt_on(container: LN) -> bool:
-    is_fmt_on = False
+def is_fmt_on(container: LN) -> bool:
+    """Determine whether formatting is switched on within a container.
+    Determined by whether the last `# fmt:` comment is `on` or `off`.
+    """
+    fmt_on = False
     for comment in list_comments(container.prefix, is_endmarker=False):
         if comment.value in FMT_ON:
-            is_fmt_on = True
+            fmt_on = True
         elif comment.value in FMT_OFF:
-            is_fmt_on = False
-    return is_fmt_on
+            fmt_on = False
+    return fmt_on
 
 
 def contains_fmt_on_at_column(container: LN, column: int) -> bool:
+    """Determine if children at a given column have formatting switched on."""
     for child in container.children:
         if (
             isinstance(child, Node)
@@ -5264,13 +5268,14 @@ def contains_fmt_on_at_column(container: LN, column: int) -> bool:
             or isinstance(child, Leaf)
             and child.column == column
         ):
-            if fmt_on(child):
+            if is_fmt_on(child):
                 return True
 
     return False
 
 
 def first_leaf_column(node: Node) -> Optional[int]:
+    """Returns the column of the first leaf child of a node."""
     for child in node.children:
         if isinstance(child, Leaf):
             return child.column
diff --git a/docs/reference/reference_functions.rst b/docs/reference/reference_functions.rst
index 459e498..fc5cefb 100644
--- a/docs/reference/reference_functions.rst
+++ b/docs/reference/reference_functions.rst
@@ -135,6 +135,12 @@ Utilities
 
 .. autofunction:: black.generate_ignored_nodes
 
+.. autofunction:: black.is_fmt_on
+
+.. autofunction:: black.contains_fmt_on_at_column
+
+.. autofunction:: black.first_leaf_column
+
 .. autofunction:: black.generate_trailers_to_omit
 
 .. autofunction:: black.get_future_imports