adding documentation

Author: roman_yakovenko

pygccxml/binary_parsers/__init__.py

@@ -6,15 +6,19 @@
 """
 contains classes that allows to extract different information from binary files
 ( .pdb, .map, .dll, .bsc, .so ) and integrate it with existing declarations tree
+
+The main function of this package is "merge_information"
 """
 
 import undname
 from parsers import merge_information
 
 def undecorate_blob( blob ):
-    """returns undecorated\unmangled string, created from blob"""
+    """returns undecorated\unmangled string, created from blob(exported symbol name)"""
     return undname.undname_creator_t().undecorate_blob( blob )
 
 def format_decl( decl, hint=None ):
-    """returns string, that represents formatted decl, according to some rules"""
+    """returns string, that represents formatted declaration, according to some rules
+    hint valid values are: "msvc" and "nm"
+    """
     return undname.undname_creator_t().format_decl( decl, hint=hint )

pygccxml/binary_parsers/parsers.py

@@ -7,8 +7,10 @@
 """
 defines few simple classes( parsers ), which deals with .dll, .map, .so files.
 
-Those classes extract decorated\mangled names from the files. Later, they undecorate
-the name and extract the functions calling convention.
+Those classes extract decorated\mangled names from the files. Later the extracted
+symbols are used for:
+* building "dynamic library" public interface
+* extracting function calling convention
 """
 
 import os
@@ -80,13 +82,13 @@ def merge( self, symbol):
         raise NotImplementedError()
 
     def parse( self ):
-        """main class method
+        """the main method of the class
 
         loads information from the binary file and merges it into the declarations
         tree.
 
-        The return value of the function is dictionary, where key is decorated
-        declaration name and value is a declaration.
+        The return value of the function is dictionary, where the key is
+        decorated/mangled declaration name and the value is a declaration.
         """
         self.__loaded_symbols = self.load_symbols()
         result = {}
@@ -103,7 +105,7 @@ def parse( self ):
 CCTS = declarations.CALLING_CONVENTION_TYPES
 
 class formated_mapping_parser_t( libparser_t ):
-    """base parser class for few MSVC binary files"""
+    """convenience class, which formats existing declarations"""
     def __init__( self, global_ns, binary_file, hint ):
         libparser_t.__init__( self, global_ns, binary_file )
         self.__formated_decls = {}
@@ -209,6 +211,7 @@ def merge( self, smbl ):
 
 
 class so_file_parser_t( formated_mapping_parser_t ):
+    """parser for Linux .so file"""
     nm_executable = 'nm'
     #numeric-sort used for mapping between mangled and unmangled name
     cmd_mangled = '%(nm)s --extern-only --dynamic --defined-only --numeric-sort %(lib)s'

pygccxml/binary_parsers/undname.py

@@ -58,7 +58,9 @@ class UNDECORATE_NAME_OPTIONS:
     SHORT_UNIQUE_NAME = UNDNAME_NO_MS_KEYWORDS | UNDNAME_NO_ACCESS_SPECIFIERS | UNDNAME_NO_ECSU
 
 class undname_creator_t:
-    """formats declarations string representation and exported symbols, so they
+    """implementation details - should not be used directly
+
+    formats declarations string representation and exported symbols, so they
     could be matched later.
 
     The class formats variables, free and member functions, symbols exported from