Clean up docstrings and flesh them out as needed

docs/coding_conventions_python.md

@@ -68,6 +68,7 @@ One statement per line.
 Even when allowed (EG `if foo: bar`) we do not combine 2 statements onto a single line.
 
 # Naming
+
 `module_name`, `package_name`, `ClassName`, `method_name`, `ExceptionName`, `function_name`, `GLOBAL_CONSTANT_NAME`, `global_var_name`, `instance_var_name`, `function_parameter_name`, `local_var_name`.
 
 Function names, variable names, and filenames should be descriptive; eschew abbreviation. In particular, do not use abbreviations that are ambiguous or unfamiliar to readers outside your project, and do not abbreviate by deleting letters within a word.

lib/python/qmk/cli/compile/json.py

@@ -12,8 +12,14 @@ import qmk.path
 
 
 @cli.argument('filename', help='Configurator JSON export')
-@cli.entrypoint('Generate a keymap.c from a QMK Configurator export.')
+@cli.entrypoint('Compile a QMK Configurator export.')
 def main(cli):
+    """Compile a QMK Configurator export.
+
+    This command creates a new keymap from a configurator export, overwriting an existing keymap if one exists.
+
+    FIXME(skullydazed): add code to check and warn if the keymap already exists
+    """
     # Error checking
     if cli.args.filename == ('-'):
         cli.log.error('Reading from STDIN is not (yet) supported.')

lib/python/qmk/cli/doctor.py

@@ -2,15 +2,24 @@
 
 Check up for QMK environment.
 """
-from milc import cli
-
 import shutil
 import platform
 import os
 
+from milc import cli
+
 
 @cli.entrypoint('Basic QMK environment checks')
 def main(cli):
+    """Basic QMK environment checks.
+
+    This is currently very simple, it just checks that all the expected binaries are on your system.
+
+    TODO(unclaimed):
+        * [ ] Run the binaries to make sure they work
+        * [ ] Compile a trivial program with each compiler
+        * [ ] Check for udev entries on linux
+    """
 
     binaries = ['dfu-programmer', 'avrdude', 'dfu-util', 'avr-gcc', 'arm-none-eabi-gcc']
 

lib/python/qmk/cli/hello.py

@@ -6,6 +6,8 @@ from milc import cli
 
 
 @cli.argument('-n', '--name', default='World', help='Name to greet.')
-@cli.entrypoint('QMK Python Hello World.')
+@cli.entrypoint('QMK Hello World.')
 def main(cli):
+    """Log a friendly greeting.
+    """
     cli.log.info('Hello, %s!', cli.config.general.name)

lib/python/qmk/cli/json/keymap.py

@@ -13,6 +13,10 @@ import qmk.keymap
 @cli.argument('filename', help='Configurator JSON file')
 @cli.entrypoint('Create a keymap.c from a QMK Configurator export.')
 def main(cli):
+    """Generate a keymap.c from a configurator export.
+
+    This command uses the `qmk.keymap` module to generate a keymap.c from a configurator export. The generated keymap is written to stdout, or to a file if -o is provided.
+    """
     # Error checking
     if cli.args.filename == ('-'):
         cli.log.error('Reading from STDIN is not (yet) supported.')

lib/python/qmk/keymap.py

@@ -1,3 +1,5 @@
+"""Functions that help you work with QMK keymaps.
+"""
 import json
 import logging
 import os
@@ -21,24 +23,37 @@ __KEYMAP_GOES_HERE__
 """
 
 
-# Helper Functions
-def template(keyboard, keymap):
+def template(keyboard):
     """Returns the `keymap.c` template for a keyboard.
 
     If a template exists in `keyboards/<keyboard>/templates/keymap.c` that
     text will be used instead of `DEFAULT_KEYMAP_C`.
+
+    Args:
+        keyboard
+            The keyboard to return a template for.
     """
     template_name = 'keyboards/%s/templates/keymap.c' % keyboard
 
     if os.path.exists(template_name):
         with open(template_name, 'r') as fd:
-            template_text = fd.read()
+            return fd.read()
 
-    return DEFAULT_KEYMAP_C.replace('__KEYMAP_GOES_HERE__', keymap)
+    return DEFAULT_KEYMAP_C
 
 
 def generate(keyboard, layout, layers):
-    """Generate the keymap source code.
+    """Returns a keymap.c for the specified keyboard, layout, and layers.
+
+    Args:
+        keyboard
+            The name of the keyboard
+
+        layout
+            The LAYOUT macro this keymap uses.
+
+        layers
+            An array of arrays describing the keymap. Each item in the inner array should be a string that is a valid QMK keycode.
     """
     layer_txt = []
     for layer_num, layer in enumerate(layers):
@@ -50,11 +65,26 @@ def generate(keyboard, layout, layers):
     keymap = '\n'.join(layer_txt)
     keymap_c = template(keyboard, keymap)
 
-    return keymap_c
+    return keymap_c.replace('__KEYMAP_GOES_HERE__', keymap)
 
 
 def write(keyboard, keymap, layout, layers):
     """Generate the `keymap.c` and write it to disk.
+
+    Returns the filename written to.
+
+    Args:
+        keyboard
+            The name of the keyboard
+
+        keymap
+            The name of the keymap
+
+        layout
+            The LAYOUT macro this keymap uses.
+
+        layers
+            An array of arrays describing the keymap. Each item in the inner array should be a string that is a valid QMK keycode.
     """
     keymap_c = generate(keyboard, layout, layers)
     keymap_path = qmk.path.keymap(keyboard)
@@ -70,7 +100,6 @@ def write(keyboard, keymap, layout, layers):
     return keymap_file
 
 
-# Public functions
 def compile_firmware(keyboard, keymap, layout, layers):
     """Compile a firmware.
     """

lib/python/qmk/path.py

@@ -5,6 +5,10 @@ import os
 
 def keymap(keyboard):
     """Locate the correct directory for storing a keymap.
+
+    Args:
+        keyboard
+            The name of the keyboard. Example: clueboard/66/rev3
     """
     for directory in ['.', '..', '../..', '../../..', '../../../..', '../../../../..']:
         basepath = os.path.normpath(os.path.join('keyboards', keyboard, directory, 'keymaps'))