Add docs

flake8/engine.py

@@ -32,6 +32,9 @@ def _register_extensions():
 
 
 def get_parser():
+    """This returns an instance of optparse.OptionParser with all the
+    extensions registered and options set. This wraps ``pep8.get_parser``.
+    """
     (extensions, parser_hooks, options_hooks) = _register_extensions()
     details = ', '.join(['%s: %s' % ext for ext in extensions])
     parser = pep8.get_parser('flake8', '%s (%s)' % (__version__, details))
@@ -67,7 +70,8 @@ class StyleGuide(pep8.StyleGuide):
 
 
 def get_style_guide(**kwargs):
-    """Parse the options and configure the checker."""
+    """Parse the options and configure the checker. This returns a sub-class 
+    of ``pep8.StyleGuide``."""
     kwargs['parser'], options_hooks = get_parser()
     styleguide = StyleGuide(**kwargs)
     options = styleguide.options

flake8/hooks.py

@@ -13,6 +13,18 @@ from flake8.main import DEFAULT_CONFIG
 
 
 def git_hook(complexity=-1, strict=False, ignore=None, lazy=False):
+    """This is the function used by the git hook.
+    
+    :param int complexity: (optional), any value > 0 enables complexity
+        checking with mccabe
+    :param bool strict: (optional), if True, this returns the total number of
+        errors which will cause the hook to fail
+    :param str ignore: (optional), a comma-separated list of errors and
+        warnings to ignore
+    :param bool lazy: (optional), allows for the instances where you don't add
+        the files to the index before running a commit, e.g., git commit -a
+    :returns: total number of errors if strict is True, otherwise 0
+    """
     gitcmd = "git diff-index --cached --name-only HEAD"
     if lazy:
         gitcmd = gitcmd.replace('--cached ', '')
@@ -30,6 +42,11 @@ def git_hook(complexity=-1, strict=False, ignore=None, lazy=False):
 
 
 def hg_hook(ui, repo, **kwargs):
+    """This is the function executed directly by Mercurial as part of the
+    hook. This is never called directly by the user, so the parameters are
+    undocumented. If you would like to learn more about them, please feel free
+    to read the official Mercurial documentation.
+    """
     complexity = ui.config('flake8', 'complexity', default=-1)
     strict = ui.configbool('flake8', 'strict', default=True)
     config = ui.config('flake8', 'config', default=True)

flake8/main.py

@@ -42,18 +42,35 @@ def main():
 
 
 def check_file(path, ignore=(), complexity=-1):
+    """Checks a file using pep8 and pyflakes by default and mccabe 
+    optionally.
+
+    :param str path: path to the file to be checked
+    :param tuple ignore: (optional), error and warning codes to be ignored
+    :param int complexity: (optional), enables the mccabe check for values > 0
+    """
     flake8_style = get_style_guide(
         config_file=DEFAULT_CONFIG, ignore=ignore, max_complexity=complexity)
     return flake8_style.input_file(path)
 
 
 def check_code(code, ignore=(), complexity=-1):
+    """Checks code using pep8 and pyflakes by default and mccabe optionally.
+
+    :param str code: code to be checked
+    :param tuple ignore: (optional), error and warning codes to be ignored
+    :param int complexity: (optional), enables the mccabe check for values > 0
+    """
     flake8_style = get_style_guide(
         config_file=DEFAULT_CONFIG, ignore=ignore, max_complexity=complexity)
     return flake8_style.input_file('-', lines=code.splitlines())
 
 
 class Flake8Command(setuptools.Command):
+    """The :class:`Flake8Command` class is used by setuptools to perform
+    checks on registered modules.
+    """
+
     description = "Run flake8 on modules registered in setuptools"
     user_options = []