config.py: Enhance and add missing comments

rpmlint/config.py

@@ -8,11 +8,15 @@ from xdg.BaseDirectory import xdg_config_dirs
 
 class Config(object):
     """
-    Class wrapping testing loading and parsing.
-    By default it loads all default locations and initializes basic testing
-    layout for the rpmlint binary.
-    Based on the opening order 'newer' configuration takes precedence over
-    already existing one.
+    Load and parse rpmlint configuration.
+
+    Configuration files are written in toml and should be placed in one of
+    the XDG_CONFIG_DIRS directory or passed as "config" argument directly.
+
+    By default it loads configdefaults.toml and all default locations and
+    initializes basic testing layout for the rpmlint binary. Based on the
+    opening order 'newer' configuration takes precedence over already
+    existing one.
     """
 
     re_filter = re.compile(r'\s*addFilter\([\"\'](.*)[\"\']\)')
@@ -20,37 +24,40 @@ class Config(object):
     config_defaults = Path(__file__).parent / 'configdefaults.toml'
 
     def __init__(self, config=None):
+        """Initialize basic options and load rpmlint configuration."""
         # ordered list of configuration files we loaded
-        # usefull when debugging where from we got all the config options
+        # useful when debugging where from we got all the config options
         self.conf_files = []
-        # Configuration content parsed from the ini file
+        # Configuration content parsed from the toml configuration file
         self.configuration = None
-        # wether to print more informations or not
+        # whether to print more information or not
         self.info = False
-        # wether to treat all messages as errors or not
+        # whether to treat all messages as errors or not
         self.strict = False
         # whether to treat individual errors as non-fatal
         self.permissive = False
+
+        # find configuration files and load them
         self.find_configs(config)
         self.load_config()
-        # loading of the configuration failed fall back only to defaults
+        # if loading of the configuration failed -> fall back only to defaults
         if not self.configuration:
             # reset the configs only to defaults
             self.conf_files = [self.config_defaults]
             self.load_config()
 
-    def set_badness(self, result, badness):
-        """
-        Set specific badness for some result
-        """
-        self.configuration['Scoring'][result] = badness
-
     def find_configs(self, config=None):
         """
-        Load all the configuration files from XDG_CONFIG_DIRS.
-        User can override and then that is added too.
-        """
+        Find and store paths to all config files.
 
+        It searches for default configuration, files in XDG_CONFIG_DIRS and
+        user defined configuration (argument "config"). All configuration
+        file paths found are then stored in self.conf_files variable.
+        XDG_CONFIG_DIRS contains preference-ordered set of base directories
+        to search for configuration files. Users can override it by their
+        own configuration file (config parameter) and then that is
+        added too.
+        """
         # first load up the file that contains defaults
         self.conf_files.append(self.config_defaults)
 
@@ -70,20 +77,15 @@ class Config(object):
             else:
                 print_warning('(none): W: error locating user requested configuration: {}'.format(config))
 
-    def print_config(self):
-        """
-        Just pretty print the current state of the config
-        """
-        if self.configuration:
-            print(toml.dumps(self.configuration))
-
     def load_config(self, config=None):
         """
-        Load the configuration files and append it to local dictionary with the
-        content of already loaded options.
+        Load the configuration files and append it to local dictionary.
+
+        It's stored in self.configuration with the content of already loaded
+        options.
         """
         if config and config not in self.conf_files:
-            # just add the config at the end of the list, someone injected
+            # just add the new config at the end of the list, someone injected
             # config file to us
             if config.exists():
                 self.conf_files.append(config)
@@ -94,14 +96,24 @@ class Config(object):
             cfg = None
         self.configuration = cfg
 
-    def load_rpmlintrc(self, rpmlint_file):
+    def load_rpmlintrc(self, rpmlintrc_file):
         """
-        Function to load up existing rpmlintrc files
-        Only setBadness and addFilter are processed
+        Load existing rpmlintrc files.
+
+        Only setBadness and addFilter are processed.
         """
-        rpmlintrc_content = rpmlint_file.read_text()
+        rpmlintrc_content = rpmlintrc_file.read_text()
         filters = self.re_filter.findall(rpmlintrc_content)
         self.configuration['Filters'] += filters
         badness = self.re_badness.findall(rpmlintrc_content)
         for entry in badness:
             self.configuration['Scoring'].update({entry[0]: entry[1]})
+
+    def print_config(self):
+        """Print the current state of the configuration."""
+        if self.configuration:
+            print(toml.dumps(self.configuration))
+
+    def set_badness(self, result, badness):
+        """Set specific badness for some result."""
+        self.configuration['Scoring'][result] = badness