Add missing docstrings

Also make the format in the code a bit more consistent.

1 files changed, 48 insertions, 40 deletions

diff --git a/kconfiglib.py b/kconfiglib.py
index 138e9fd..9a0473f 100644
--- a/kconfiglib.py
+++ b/kconfiglib.py
@@ -301,8 +301,6 @@ Send bug reports, suggestions, and questions to ulfalizer a.t Google's email
 service, or open a ticket on the GitHub page.
 """
 
-# TODO: consistent docstring format
-
 import errno
 import os
 import platform
@@ -419,7 +417,6 @@ class Kconfig(object):
       Like for srctree, only the value of $CONFIG_ when the configuration is
       loaded matters.
     """
-
     __slots__ = (
         "_choices",
         "_print_undef_assign",
@@ -481,7 +478,6 @@ class Kconfig(object):
           Kconfig.enable/disable_warnings(). It is provided as a constructor
           argument since warnings might be generated during parsing.
         """
-
         self.srctree = os.environ.get("srctree")
 
         self.config_prefix = os.environ.get("CONFIG_")
@@ -627,7 +623,6 @@ class Kconfig(object):
           True if all existing user values should be cleared before loading the
           .config.
         """
-
         with self._open(filename) as f:
             if replace:
                 # Invalidates all symbols as a side effect
@@ -787,7 +782,6 @@ class Kconfig(object):
         Resets the user values of all symbols, as if Kconfig.load_config() or
         Symbol.set_value() had never been called.
         """
-
         # set_value() already rejects undefined symbols, and they don't need to
         # be invalidated (because their value never changes), so we can just
         # iterate over defined symbols
@@ -830,7 +824,8 @@ class Kconfig(object):
 
     def __repr__(self):
         """
-        Prints some general information when a Kconfig object is evaluated.
+        Returns a string with information about the Kconfig object when it is
+        evaluated on e.g. the interactive Python prompt.
         """
         return "<{}>".format(", ".join((
             "configuration with {} symbols".format(len(self.syms)),
@@ -990,7 +985,6 @@ class Kconfig(object):
         and string operations where possible. This is the biggest hotspot
         during parsing.
         """
-
         s = self._line
 
         # Tricky implementation detail: While parsing a token, 'token' refers
@@ -1274,7 +1268,6 @@ class Kconfig(object):
         Returns the final menu node in the block (or prev_node if the block is
         empty). This allows chaining.
         """
-
         while 1:
             # We might already have tokens from parsing a line to check if it's
             # a property and discovering it isn't. This is a kind of "unget".
@@ -1456,7 +1449,6 @@ class Kconfig(object):
           'visible if' dependencies from enclosing menus. Propagated to Symbol
           and Choice prompts.
         """
-
         # New properties encountered at this location. A local 'depends on'
         # only applies to these, in case a symbol is defined in multiple
         # locations.
@@ -1646,6 +1638,7 @@ class Kconfig(object):
 
         if isinstance(node.item, (Symbol, Choice)):
             if isinstance(node.item, Symbol):
+                # See the class documentation
                 node.item.direct_dep = \
                     self._make_or(node.item.direct_dep, node.dep)
 
@@ -1703,7 +1696,6 @@ class Kconfig(object):
           True if m should be rewritten to m && MODULES. See the
           Kconfig.eval_string() documentation.
         """
-
         # Grammar:
         #
         #   expr:     and_expr ['||' expr]
@@ -1794,7 +1786,6 @@ class Kconfig(object):
         The calculated sets might be larger than necessary as we don't do any
         complex analysis of the expressions.
         """
-
         # The directly dependent symbols of a symbol S are:
         #
         #  - Any symbols whose prompts, default values, rev_dep (select
@@ -1859,7 +1850,6 @@ class Kconfig(object):
         """
         Returns a list containing all .config strings for the configuration.
         """
-
         # Symbol._already_written is set to True when a symbol config string is
         # fetched, so that symbols defined in multiple locations only get one
         # .config entry. We reset it prior to writing out a new .config. It
@@ -1922,7 +1912,6 @@ class Kconfig(object):
         Expands $-references to symbols in 's' to symbol values, or to the
         empty string for undefined symbols.
         """
-
         while 1:
             sym_ref_match = _sym_ref_re_search(s)
             if not sym_ref_match:
@@ -2035,7 +2024,7 @@ class Symbol(object):
 
       Some handy 'assignable' idioms:
 
-        # Is the symbol assignable (visible)?
+        # Is 'sym' an assignable (visible) bool/tristate symbol?
         if sym.assignable:
             # What's the highest value it can be assigned? [-1] in Python
             # gives the last element.
@@ -2060,7 +2049,7 @@ class Symbol(object):
       The user value of the symbol. None if no user value has been assigned
       (via Kconfig.load_config() or Symbol.set_value()).
 
-      0, 1, or 2 for bool/tristate symbols, and a string for other symbol
+      0, 1, or 2 for bool/tristate symbols, and a string for the other symbol
       types.
 
       Warning: Do not assign directly to this. It will break things. Use
@@ -2127,8 +2116,10 @@ class Symbol(object):
     direct_dep:
       The 'depends on' dependencies. If a symbol is defined in multiple
       locations, the dependencies at each location are ORed together.
+
       Internally, this is only used to implement 'imply', which only applies if
-      the implied symbol has expr_value(self.direct_dep) != 0.
+      the implied symbol has expr_value(self.direct_dep) != 0. 'depends on' is
+      automatically propagated to the conditions of all properties.
 
     env_var:
       If the Symbol has an 'option env="FOO"' option, this contains the name
@@ -2156,7 +2147,6 @@ class Symbol(object):
     kconfig:
       The Kconfig instance this symbol is from.
     """
-
     __slots__ = (
         "_already_written",
         "_cached_assignable",
@@ -2206,7 +2196,6 @@ class Symbol(object):
         """
         See the class documentation.
         """
-
         if self._cached_str_val is not None:
             return self._cached_str_val
 
@@ -2311,7 +2300,6 @@ class Symbol(object):
         """
         See the class documentation.
         """
-
         if self._cached_tri_val is not None:
             return self._cached_tri_val
 
@@ -2408,7 +2396,6 @@ class Symbol(object):
         """
         See the class documentation.
         """
-
         if self.env_var is not None:
             # Corresponds to SYMBOL_AUTO being set in the C implementation
             return None
@@ -2446,10 +2433,12 @@ class Symbol(object):
         file. For bool and tristate symbols, use the 'assignable' attribute to
         check which values can currently be assigned. Setting values outside
         'assignable' will cause Symbol.user_str/tri_value to differ from
-        Symbol.str/tri_value (be truncated down or up). Values that are invalid
-        for the type (such as "foo" or "m" for a BOOL) are ignored and won't be
-        stored in Symbol.user_str/tri_value (Kconfiglib will print a warning by
-        default).
+        Symbol.str/tri_value (be truncated down or up).
+
+        Assigning a 1 (m) or 2 (y) value to a choice symbol automatically
+        changes the mode of the choice (see the Choice class). Setting a choice
+        symbol to 2 (y) makes it the currently selected choice symbol, which is
+        significant for choices in y mode.
 
         Other symbols that depend (possibly indirectly) on this symbol are
         automatically recalculated to reflect the assigned value.
@@ -2459,8 +2448,9 @@ class Symbol(object):
           pass 0, 1, 2 for n, m, and y, respectively. For other symbol types,
           pass a string.
 
-          A warning will be printed by default if the value is not valid for
-          the symbol's type.
+          Values that are invalid for the type (such as "foo" or 1 (m) for a
+          BOOL) are ignored and won't be stored in Symbol.user_str/tri_value.
+          Kconfiglib will print a warning by default for invalid assignments.
         """
         self._set_value_no_invalidate(value, False)
 
@@ -2563,7 +2553,6 @@ class Symbol(object):
         Symbol constructor -- not intended to be called directly by Kconfiglib
         clients.
         """
-
         # These attributes are always set on the instance from outside and
         # don't need defaults:
         #   _already_written
@@ -2609,7 +2598,6 @@ class Symbol(object):
         """
         Worker function for the 'assignable' attribute.
         """
-
         if self.orig_type not in (BOOL, TRISTATE):
             return ()
 
@@ -2656,7 +2644,6 @@ class Symbol(object):
           spammy for Linux defconfigs, so turn it off when loading .configs.
           It's still helpful when manually invoking set_value().
         """
-
         # Check if the value is valid for our type
         if not ((self.orig_type == BOOL     and value in (0, 2)       ) or
                 (self.orig_type == TRISTATE and value in (0, 1, 2)    ) or
@@ -2693,9 +2680,8 @@ class Symbol(object):
 
         self.user_value = value
 
-        # TODO: assigning automatically changes choice yada yada
-
         if self.choice is not None:
+            # Change mode of choice
             if self.user_value == 2:
                 self.choice.user_value = 2
                 self.choice.user_selection = self
@@ -3239,7 +3225,8 @@ class MenuNode(object):
 
     def __repr__(self):
         """
-        TODO
+        Returns a string with information about the menu node when it is
+        evaluated on e.g. the interactive Python prompt.
         """
         fields = []
 
@@ -3290,7 +3277,12 @@ class MenuNode(object):
 
     def __str__(self):
         """
-        TODO
+        Returns a string representation of the MenuNode, matching the Kconfig
+        format.
+
+        For Symbol and Choice menu nodes, this function simply calls through to
+        MenuNode.item.__str__(). For MENU and COMMENT nodes, a Kconfig-like
+        representation of the menu or comment is returned.
         """
         if isinstance(self.item, (Symbol, Choice)):
             return self.item.__str__()
@@ -3328,7 +3320,15 @@ class InternalError(Exception):
 
 def expr_value(expr):
     """
-    TODO
+    Evaluates the expression 'expr' to a tristate value. Returns 0 (n), 1 (m),
+    or 2 (y).
+
+    'expr' must be an already-parsed expression from a Symbol, Choice, or
+    MenuNode. To evaluate an expression represented as a string, use
+    Kconfig.eval_string().
+
+    Passing subexpressions of expressions to this function is allowed and works
+    as expected.
     """
     if isinstance(expr, Symbol):
         return expr.tri_value
@@ -3385,7 +3385,11 @@ def expr_value(expr):
 
 def expr_str(expr):
     """
-    TODO
+    Returns the string representation of the expression 'expr', as in a Kconfig
+    file.
+
+    Passing subexpressions of expressions to this function is allowed and works
+    as expected.
     """
     if isinstance(expr, Symbol):
         if expr.is_constant:
@@ -3409,18 +3413,22 @@ def expr_str(expr):
                              _RELATION_TO_STR[expr[0]],
                              expr_str(expr[2]))
 
+# escape()/unescape() helpers
 _escape_re_sub = re.compile(r'(["\\])').sub
 _unescape_re_sub = re.compile(r"\\(.)").sub
 
 def escape(s):
-    """
-    TODO
+    r"""
+    Escapes the string 's' in the same fashion as is done for display in
+    Kconfig format and when writing strings to a .config file. " and \ are
+    replaced by \" and \\, respectively.
     """
     return _escape_re_sub(r"\\\1", s)
 
 def unescape(s):
-    """
-    TODO
+    r"""
+    Unescapes the string 's'. Any character preceded by a \ is replaced with
+    just that character. Used internally when reading .config files.
     """
     return _unescape_re_sub(r"\1", s)