Convert some comments to module docstrings in utilities

This makes running pydoc(3) on the utilities helpful.

Reuse the module docstring for the --help text for utilities that use
argparse.

Also fix some copy-paste errors in the all*config.py descriptions and
clean up the language a bit.

Piggyback removal of an optimization in allmodconfig.py that's pretty
irrelevant now.

10 files changed, 128 insertions, 131 deletions

diff --git a/alldefconfig.py b/alldefconfig.py
index 4f0cbca..f132f1e 100755
--- a/alldefconfig.py
+++ b/alldefconfig.py
@@ -3,15 +3,17 @@
 # Copyright (c) 2018-2019, Ulf Magnusson
 # SPDX-License-Identifier: ISC
 
-# Works like 'make alldefconfig'. Verified by the test suite to generate
-# identical output to 'make alldefconfig' for all ARCHes.
-#
-# The default output filename is '.config'. A different filename can be passed
-# in the KCONFIG_CONFIG environment variable.
-#
-# Usage for the Linux kernel:
-#
-#   $ make [ARCH=<arch>] scriptconfig SCRIPT=Kconfiglib/alldefconfig.py
+"""
+Writes a configuration file where all symbols are set to their their default
+values.
+
+The default output filename is '.config'. A different filename can be passed in
+the KCONFIG_CONFIG environment variable.
+
+Usage for the Linux kernel:
+
+  $ make [ARCH=<arch>] scriptconfig SCRIPT=Kconfiglib/alldefconfig.py
+"""
 
 import kconfiglib
 
diff --git a/allmodconfig.py b/allmodconfig.py
index f7c6608..b41cf23 100755
--- a/allmodconfig.py
+++ b/allmodconfig.py
@@ -3,15 +3,16 @@
 # Copyright (c) 2018-2019, Ulf Magnusson
 # SPDX-License-Identifier: ISC
 
-# Works like 'make allmodconfig'. Verified by the test suite to generate output
-# identical to 'make allmodconfig', for all ARCHES.
-#
-# The default output filename is '.config'. A different filename can be passed
-# in the KCONFIG_CONFIG environment variable.
-#
-# Usage for the Linux kernel:
-#
-#   $ make [ARCH=<arch>] scriptconfig SCRIPT=Kconfiglib/examples/allyesconfig.py
+"""
+Writes a configuration file where as many symbols as possible are set to 'm'.
+
+The default output filename is '.config'. A different filename can be passed
+in the KCONFIG_CONFIG environment variable.
+
+Usage for the Linux kernel:
+
+  $ make [ARCH=<arch>] scriptconfig SCRIPT=Kconfiglib/examples/allmodconfig.py
+"""
 
 import kconfiglib
 
@@ -22,22 +23,18 @@ def main():
     # See allnoconfig.py
     kconf.disable_warnings()
 
-    # Small optimizations
-    BOOL = kconfiglib.BOOL
-    TRISTATE = kconfiglib.TRISTATE
-
     for sym in kconf.unique_defined_syms:
-        if sym.orig_type == BOOL:
+        if sym.orig_type == kconfiglib.BOOL:
             # 'bool' choice symbols get their default value, as determined by
             # e.g. 'default's on the choice
             if not sym.choice:
                 # All other bool symbols get set to 'y', like for allyesconfig
                 sym.set_value(2)
-        elif sym.orig_type == TRISTATE:
+        elif sym.orig_type == kconfiglib.TRISTATE:
             sym.set_value(1)
 
     for choice in kconf.unique_choices:
-        choice.set_value(2 if choice.orig_type == BOOL else 1)
+        choice.set_value(2 if choice.orig_type == kconfiglib.BOOL else 1)
 
     kconf.enable_warnings()
 
diff --git a/allnoconfig.py b/allnoconfig.py
index d4aa8d0..9b66d83 100755
--- a/allnoconfig.py
+++ b/allnoconfig.py
@@ -3,17 +3,19 @@
 # Copyright (c) 2018-2019, Ulf Magnusson
 # SPDX-License-Identifier: ISC
 
-# Works like 'make allnoconfig'. Verified by the test suite to generate
-# identical output to 'make allnoconfig' for all ARCHes.
-#
-# See the examples/allnoconfig_walk.py example script for another variant.
-#
-# The default output filename is '.config'. A different filename can be passed
-# in the KCONFIG_CONFIG environment variable.
-#
-# Usage for the Linux kernel:
-#
-#   $ make [ARCH=<arch>] scriptconfig SCRIPT=Kconfiglib/allnoconfig.py
+"""
+Writes a configuration file where as many symbols as possible are set to 'n'.
+
+The default output filename is '.config'. A different filename can be passed
+in the KCONFIG_CONFIG environment variable.
+
+Usage for the Linux kernel:
+
+  $ make [ARCH=<arch>] scriptconfig SCRIPT=Kconfiglib/examples/allmodconfig.py
+
+See the examples/allnoconfig_walk.py example script for another way to
+implement this script.
+"""
 
 import kconfiglib
 
diff --git a/allyesconfig.py b/allyesconfig.py
index e475329..afff0e7 100755
--- a/allyesconfig.py
+++ b/allyesconfig.py
@@ -3,33 +3,16 @@
 # Copyright (c) 2018-2019, Ulf Magnusson
 # SPDX-License-Identifier: ISC
 
-# Works like 'make allyesconfig'. Verified by the test suite to generate output
-# identical to 'make allyesconfig', for all ARCHES.
-#
-# In theory, we need to handle choices in two different modes:
-#
-#   y: One symbol is y, the rest are n
-#   m: Any number of symbols are m, the rest are n
-#
-# Only tristate choices can be in m mode.
-#
-# Here's a convoluted example of how you might get an m-mode choice even during
-# allyesconfig:
-#
-#   choice
-#           tristate "weird choice"
-#           depends on m
-#
-#   ...
-#
-#   endchoice
-#
-# The default output filename is '.config'. A different filename can be passed
-# in the KCONFIG_CONFIG environment variable.
-#
-# Usage for the Linux kernel:
-#
-#   $ make [ARCH=<arch>] scriptconfig SCRIPT=Kconfiglib/examples/allyesconfig.py
+"""
+Writes a configuration file where as many symbols as possible are set to 'y'.
+
+The default output filename is '.config'. A different filename can be passed
+in the KCONFIG_CONFIG environment variable.
+
+Usage for the Linux kernel:
+
+  $ make [ARCH=<arch>] scriptconfig SCRIPT=Kconfiglib/examples/allmodconfig.py
+"""
 
 import kconfiglib
 
@@ -50,6 +33,13 @@ def main():
         # 'y' mode (the "normal" mode), which will instead just get their
         # default selection, but will set all symbols in m-mode choices to 'm',
         # which is as high as they can go.
+        #
+        # Here's a convoluted example of how you might get an m-mode choice
+        # even during allyesconfig:
+        #
+        #   choice
+        #           tristate "weird choice"
+        #           depends on m
         sym.set_value(1 if sym.choice else 2)
 
     # Set all choices to the highest possible mode
diff --git a/genconfig.py b/genconfig.py
index f83fd4c..23ba4b8 100755
--- a/genconfig.py
+++ b/genconfig.py
@@ -3,18 +3,17 @@
 # Copyright (c) 2018-2019, Ulf Magnusson
 # SPDX-License-Identifier: ISC
 
-# Generates a C header from the configuration, matching the format of
-# include/generated/autoconf.h in the kernel.
-#
-# Optionally generates a directory structure with one file per symbol that can
-# be used to implement incremental builds. See the docstring for
-# Kconfig.sync_deps() in Kconfiglib.
-#
-# Usage (see argument help texts for more information):
-#
-#   genconfig.py [-h] [--header-path HEADER_FILE]
-#                [--sync-deps [OUTPUT_DIR]] [--config-out CONFIG_FILE]
-#                [KCONFIG_FILENAME]
+"""
+Generates a header file with #defines from the configuration, matching the
+format of include/generated/autoconf.h in the Linux kernel.
+
+Optionally creates/updates a directory structure with one file per symbol that
+can be used to implement incremental builds. See the docstring for
+Kconfig.sync_deps() in kconfiglib.py.
+
+By default, the configuration is generated from '.config'. A different
+configuration file can be passed in the KCONFIG_CONFIG environment variable.
+"""
 
 import argparse
 
@@ -26,12 +25,9 @@ DEFAULT_SYNC_DEPS_PATH = "deps/"
 
 
 def main():
-    parser = argparse.ArgumentParser(description="""
-Generates a header file with defines from the configuration. Optionally
-creates/updates a directory with incremental build information as well (see the
-docstring for the Kconfig.sync_deps() function in Kconfiglib). The .config file
-to generate the configuration from can be specified by setting the
-KCONFIG_CONFIG environment variable.""")
+    parser = argparse.ArgumentParser(
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description=__doc__)
 
     parser.add_argument(
         "--header-path",
diff --git a/listnewconfig.py b/listnewconfig.py
index 975b716..45f6a57 100755
--- a/listnewconfig.py
+++ b/listnewconfig.py
@@ -3,11 +3,13 @@
 # Copyright (c) 2018-2019, Ulf Magnusson
 # SPDX-License-Identifier: ISC
 
-# Works like 'make listnewconfig', listing all modifiable symbols that are not
-# assigned in the configuration file.
-#
-# The default output filename is '.config'. A different filename can be passed
-# in the KCONFIG_CONFIG environment variable.
+"""
+List all user-modifiable symbols that are not given a value in the configuration
+file. Usually, these are new symbols that have been added to the Kconfig files.
+
+The default configuration filename is '.config'. A different filename can be
+passed in the KCONFIG_CONFIG environment variable.
+"""
 
 import sys
 
diff --git a/oldconfig.py b/oldconfig.py
index 1593290..6f9950e 100755
--- a/oldconfig.py
+++ b/oldconfig.py
@@ -3,23 +3,25 @@
 # Copyright (c) 2018-2019, Ulf Magnusson
 # SPDX-License-Identifier: ISC
 
-# Implements oldconfig functionality:
-#
-#   1. Load existing .config
-#   2. Prompt the user for the value of all modifiable symbols/choices that
-#      aren't already set in the .config
-#   3. Write new .config
-#
-# The default input/output filename is '.config'. A different filename can be
-# passed in the KCONFIG_CONFIG environment variable.
-#
-# Unlike 'make oldconfig', this script doesn't print menu titles and comments,
-# but gives Kconfig definition locations. Printing menus and comments would be
-# pretty easy to add: Look at the parents of each item and print all menu
-# prompts and comments unless they have already been printed (assuming you want
-# to skip "irrelevant" menus).
-#
-# Entering '?' displays the help text of the symbol/choice, if any.
+"""
+Implements oldconfig functionality.
+
+  1. Loads existing .config
+  2. Prompts for the value of all modifiable symbols/choices that
+     aren't already set in the .config
+  3. Writes an updated .config
+
+The default input/output filename is '.config'. A different filename can be
+passed in the KCONFIG_CONFIG environment variable.
+
+Entering '?' displays the help text of the symbol/choice, if any.
+
+Unlike 'make oldconfig', this script doesn't print menu titles and comments,
+but gives Kconfig definition locations. Printing menus and comments would be
+pretty easy to add: Look at the parents of each item, and print all menu
+prompts and comments unless they have already been printed (assuming you want
+to skip "irrelevant" menus).
+"""
 
 from __future__ import print_function
 
diff --git a/olddefconfig.py b/olddefconfig.py
index 7edb76f..5c400de 100755
--- a/olddefconfig.py
+++ b/olddefconfig.py
@@ -3,13 +3,15 @@
 # Copyright (c) 2018-2019, Ulf Magnusson
 # SPDX-License-Identifier: ISC
 
-# Works like 'make olddefconfig', updating an old .config file or creating a
-# new one by filing in default values for all new symbols. This is the same as
-# picking the default selection for all symbols in oldconfig, or entering the
-# menuconfig interface and immediately saving.
-#
-# The default output filename is '.config'. A different filename can be passed
-# in the KCONFIG_CONFIG environment variable.
+"""
+Updates an old .config file or creates a new one, by filing in default values
+for all new symbols. This is the same as picking the default selection for all
+symbols in oldconfig, or entering the menuconfig interface and immediately
+saving.
+
+The default input/output filename is '.config'. A different filename can be
+passed in the KCONFIG_CONFIG environment variable.
+"""
 
 import kconfiglib
 
diff --git a/savedefconfig.py b/savedefconfig.py
index 19a403b..9408633 100755
--- a/savedefconfig.py
+++ b/savedefconfig.py
@@ -3,15 +3,7 @@
 # Copyright (c) 2019, Ulf Magnusson
 # SPDX-License-Identifier: ISC
 
-import argparse
-
-import kconfiglib
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        description="""
+"""
 Saves a minimal configuration file that only lists symbols that differ in value
 their defaults. Loading such a configuration file is equivalent to loading the
 "full" configuration file.
@@ -24,7 +16,17 @@ can be passed in the KCONFIG_CONFIG environment variable.
 
 Note: Minimal configurations can also be generated from within the menuconfig
 interface.
-""")
+"""
+
+import argparse
+
+import kconfiglib
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description=__doc__)
 
     parser.add_argument(
         "--kconfig",
diff --git a/setconfig.py b/setconfig.py
index 60ee9d0..dce9950 100755
--- a/setconfig.py
+++ b/setconfig.py
@@ -3,16 +3,7 @@
 # Copyright (c) 2019, Ulf Magnusson
 # SPDX-License-Identifier: ISC
 
-import argparse
-import sys
-
-import kconfiglib
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        description="""
+"""
 Simple utility for setting configuration values from the command line.
 
 Sample usage:
@@ -25,7 +16,18 @@ The exit status on errors is 1.
 
 The default input/output configuration file is '.config'. A different filename
 can be passed in the KCONFIG_CONFIG environment variable.
-""")
+"""
+
+import argparse
+import sys
+
+import kconfiglib
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description=__doc__)
 
     parser.add_argument(
         "--kconfig",