Updated all docstrings to be compatible with PEP 257

It's nicer to be compatible with the standards.

I have added one more field to the description of each function:
Side effects. This feild contains the expected side effects of
running a particular method. If the side effects of a method are
None, it is expected that the function does not change anything in
any envoronment and that running it multiple times with the same
arguments will produce the same result every time. That is when
Side effects is non, the method is expected to be pure.

Author: theotherjimmy

tools/toolchains/__init__.py

@@ -789,8 +789,16 @@ def compile_command(self, source, object, includes):
 
     @abstractmethod
     def parse_dependencies(self, dep_path):
-        """Take in a dependency file generated by the compiler and build a list of
-           all files that the dep_path depends on.
+        """Parse the dependency information generated by the compiler.
+
+        Positional arguments:
+        dep_path -- the path to a file generated by a previous run of the compiler
+
+        Return value:
+        A list of all source files that the dependency file indicated were dependencies
+
+        Side effects:
+        None
         """
         raise NotImplemented
 
@@ -799,7 +807,16 @@ def is_not_supported_error(self, output):
 
     @abstractmethod
     def parse_output(self, output):
-        """Take in compiler output and extract sinlge line warnings and errors from it
+        """Take in compiler output and extract sinlge line warnings and errors from it.
+
+        Positional arguments:
+        output -- a string of all the messages emitted by a run of the compiler
+
+        Return value:
+        None
+
+        Side effects:
+        call self.cc_info or self.notify with a description of the event generated by the compiler
         """
         raise NotImplemented
 
@@ -978,56 +995,142 @@ def get_config_header(self):
     def get_config_option(self, config_header):
         """Generate the compiler option that forces the inclusion of the configuration
         header file.
+
+        Positional arguments:
+        config_header -- The configuration header that will be included within all source files
+
+        Return value:
+        A list of the command line arguments that will force the inclusion the specified header
+
+        Side effects:
+        None
         """
         raise NotImplemented
 
     @abstractmethod
     def assemble(self, source, object, includes):
-        """Generate the command line that:
-         - Assembles the given assembly *source* file.
-         - Puts the results into the file named *object*.
-         - Has an include search path that includes everything in *includes*
+        """Generate the command line that assembles.
+
+        Positional arguments:
+        source -- a file path that is the file to assemble
+        object -- a file path that is the destination object
+        includes -- a list of all directories where header files may be found
+
+        Return value:
+        The complete command line, as a list, that would invoke the assembler
+        on the source file, include all the include paths, and generate
+        the specified object file.
+
+        Side effects:
+        None
+
+        Note:
+        This method should be decorated with @hook_tool.
         """
         raise NotImplemented
 
     @abstractmethod
     def compile_c(self, source, object, includes):
-        """Generate the command line that:
-         - Compiles the given C *source* file.
-         - Puts the results into the file named *object*.
-         - Has an include search path that includes everything in *includes*
+        """Generate the command line that compiles a C source file.
+
+        Positional arguments:
+        source -- the C source file to compile
+        object -- the destination object file
+        includes -- a list of all the directories where header files may be found
+
+        Return value:
+        The complete command line, as a list, that would invoke the C compiler
+        on the source file, include all the include paths, and generate the
+        specified object file.
+
+        Side effects:
+        None
+
+        Note:
+        This method should be decorated with @hook_tool.
         """
         raise NotImplemented
 
     @abstractmethod
     def compile_cpp(self, source, object, includes):
-        """Generate the command line that:
-         - Compiles the given C++ *source* file.
-         - Puts the results into the file named *object*.
-         - Has an include search path that includes everything in *includes*
+        """Generate the command line that compiles a C++ source file.
+
+        Positional arguments:
+        source -- the C++ source file to compile
+        object -- the destination object file
+        includes -- a list of all the directories where header files may be found
+
+        Return value:
+        The complete command line, as a list, that would invoke the C++ compiler
+        on the source file, include all the include paths, and generate the
+        specified object file.
+
+        Side effects:
+        None
+
+        Note:
+        This method should be decorated with @hook_tool.
         """
         raise NotImplemented
 
     @abstractmethod
     def link(self, output, objects, libraries, lib_dirs, mem_map):
-        """Run the link command that will:
-         - Emit a file named *output*
-         - Includes all *objects* and *libraries*
-         - Searches for libraries in *lib_dirs*
-         - Generates a memory map file in the file *mem_map*
+        """Run the linker to create an executable and memory map.
+
+        Positional arguments:
+        output -- the file name to place the executable in
+        objects -- all of the object files to link
+        libraries -- all of the required libraries
+        lib_dirs -- where the required libraries are located
+        mem_map -- the location where the memory map file should be stored
+
+        Return value:
+        None
+
+        Side effect:
+        Runs the linker to produce the executable.
+
+        Note:
+        This method should be decorated with @hook_tool.
         """
         raise NotImplemented
 
     @abstractmethod
     def archive(self, objects, lib_path):
-        """Run the command line that creates an archive containing *objects*, and named *lib_path*
+        """Run the command line that creates an archive.
+
+        Positional arguhments:
+        objects -- a list of all the object files that should be archived
+        lib_path -- the file name of the resulting library file
+
+        Return value:
+        None
+
+        Side effect:
+        Runs the archiving tool to produce the library file.
+
+        Note:
+        This method should be decorated with @hook_tool.
         """
         raise NotImplemented
 
     @abstractmethod
     def binary(self, resources, elf, bin):
-        """Run the command line that will Extract a binary named *bin* from an
-        elf file named *elf*.
+        """Run the command line that will Extract a simplified binary file.
+
+        Positional arguments:
+        resources -- A resources object (Is not used in any of the toolchains)
+        elf -- the executable file that is to be converted
+        bin -- the file name of the to be created simplified binary file
+
+        Return value:
+        None
+
+        Side effect:
+        Runs the elf2bin tool to produce the simplified binary file.
+
+        Note:
+        This method should be decorated with @hook_tool.
         """
         raise NotImplemented