Document functions and methods added during parallel linting refactoring

pylint/lint.py

@@ -913,15 +913,20 @@ def should_analyze_file(modname, path, is_argument=False):
     # pylint: enable=unused-argument
 
     def initialize(self):
+        """Initialize linter for linting
+
+        This method is called before any linting is done.
+        """
         # initialize msgs_state now that all messages have been registered into
         # the store
         for msg in self.msgs_store.messages:
             if not msg.may_be_emitted():
                 self._msgs_state[msg.msgid] = False
 
     def check(self, files_or_modules):
-        """main checking entry: check a list of files or modules from their
-        name.
+        """main checking entry: check a list of files or modules from their name.
+
+        files_or_modules is either a string or list of strings presenting modules to check.
         """
 
         self.initialize()
@@ -973,6 +978,17 @@ def _check_files(self, get_ast, file_descrs):
                 self._check_file(get_ast, check_astroid_module, name, filepath, modname)
 
     def _check_file(self, get_ast, check_astroid_module, name, filepath, modname):
+        """Check a file using the passed utility functions (get_ast and check_astroid_module)
+
+        get_ast: callable returning AST from defined file taking the following arguments
+        - filepath: path to the file to check
+        - name: Python module name
+        check_astroid_module: callable checking an AST taking the following arguments
+        - ast: AST of the module
+        name: full name of the module
+        filepath: path to checked file
+        modname: name of the checked Python module
+        """
         self.set_current_module(name, filepath)
         # get the module representation
         ast_node = get_ast(filepath, name)
@@ -995,6 +1011,11 @@ def _check_file(self, get_ast, check_astroid_module, name, filepath, modname):
 
     @staticmethod
     def _get_file_descr_from_stdin(filepath):
+        """Return file description (tuple of module name, file path, base name) from given file path
+
+        This method is used for creating suitable file description for _check_files when the
+        source is standard input.
+        """
         try:
             # Note that this function does not really perform an
             # __import__ but may raise an ImportError exception, which
@@ -1006,6 +1027,10 @@ def _get_file_descr_from_stdin(filepath):
         return (modname, filepath, filepath)
 
     def _iterate_file_descrs(self, files_or_modules):
+        """Return generator yielding file descriptions (tuples of module name, file path, base name)
+
+        The returned generator yield one item for each Python module that should be linted.
+        """
         for descr in self._expand_files(files_or_modules):
             name, filepath, is_arg = descr["name"], descr["path"], descr["isarg"]
             if self.should_analyze_file(name, filepath, is_argument=is_arg):
@@ -1042,6 +1067,10 @@ def set_current_module(self, modname, filepath=None):
 
     @contextlib.contextmanager
     def _astroid_module_checker(self):
+        """Context manager for checking ASTs
+
+        The value in the context is callable accepting AST as its only argument.
+        """
         walker = ASTWalker(self)
         _checkers = self.prepare_checkers()
         tokencheckers = [
@@ -1089,7 +1118,10 @@ def get_ast(self, filepath, modname):
             self.add_message("astroid-error", args=(ex.__class__, ex))
 
     def check_astroid_module(self, ast_node, walker, rawcheckers, tokencheckers):
-        """Check a module from its astroid representation."""
+        """Check a module from its astroid representation.
+
+        For return value see _check_astroid_module
+        """
         before_check_statements = walker.nbstatements
 
         retval = self._check_astroid_module(
@@ -1103,6 +1135,18 @@ def check_astroid_module(self, ast_node, walker, rawcheckers, tokencheckers):
         return retval
 
     def _check_astroid_module(self, ast_node, walker, rawcheckers, tokencheckers):
+        """Check given AST node with given walker and checkers
+
+        ast_mode: AST node of the module to check
+        walker: pylint.utils.ast_walker.ASTWalker instance
+        rawcheckers: List of token checkers to use
+        tokencheckers: List of raw checkers to use
+
+        Returns: bool
+        - True when the module was checked
+        - False when the module was ignored
+        - None when the contents of the module could not be parsed
+        """
         try:
             tokens = utils.tokenize_module(ast_node)
         except tokenize.TokenError as ex: