[pygccxml-commit] SF.net SVN: pygccxml:[1541] pygccxml_dev/pygccxml/binary_parsers

[<rom...@us...>]

Revision: 1541
          http://pygccxml.svn.sourceforge.net/pygccxml/?rev=1541&view=rev
Author:   roman_yakovenko
Date:     2009-01-06 13:06:23 +0000 (Tue, 06 Jan 2009)

Log Message:
-----------
adding documentation

Modified Paths:
--------------
    pygccxml_dev/pygccxml/binary_parsers/__init__.py
    pygccxml_dev/pygccxml/binary_parsers/parsers.py
    pygccxml_dev/pygccxml/binary_parsers/undname.py

Modified: pygccxml_dev/pygccxml/binary_parsers/__init__.py
===================================================================
--- pygccxml_dev/pygccxml/binary_parsers/__init__.py	2009-01-06 10:02:45 UTC (rev 1540)
+++ pygccxml_dev/pygccxml/binary_parsers/__init__.py	2009-01-06 13:06:23 UTC (rev 1541)
@@ -3,9 +3,14 @@
 # accompanying file LICENSE_1_0.txt or copy at
 # http://www.boost.org/LICENSE_1_0.txt)
 
-import sys
+"""
+contains classes that allows to extract different information from binary files
+( .pdb, .map, .dll, .bsc, .so ) and integrate it with existing declarations tree
+"""
+
 import undname
 from parsers import merge_information
 
 def undecorate_blob( blob ):
+    """returns undecorated\unmangled string, created from blob"""
     return undname.undname_creator_t().undecorate_blob( blob )

Modified: pygccxml_dev/pygccxml/binary_parsers/parsers.py
===================================================================
--- pygccxml_dev/pygccxml/binary_parsers/parsers.py	2009-01-06 10:02:45 UTC (rev 1540)
+++ pygccxml_dev/pygccxml/binary_parsers/parsers.py	2009-01-06 13:06:23 UTC (rev 1541)
@@ -3,6 +3,14 @@
 # accompanying file LICENSE_1_0.txt or copy at
 # http://www.boost.org/LICENSE_1_0.txt)
 
+
+"""
+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.
+"""
+
 import os
 import re
 import sys
@@ -31,7 +39,11 @@
 """
 
 class libparser_t( object ):
+    """base class for .dll, .map, .so parser classes"""
     def __init__( self, global_ns, binary_file ):
+        """global_ns - reference to global namespace
+        binary_file - s
+        """
         self.__global_ns = global_ns
         self.__binary_file = binary_file
         self.__loaded_symbols = None
@@ -48,16 +60,33 @@
 
     @property
     def loaded_symbols( self ):
-        """list of symbols, which were loaded from the binary file"""
+        """list of symbols, which were loaded from the binary file.
+        The actual type of return value defined by the derived class"""
         return self.__loaded_symbols
 
     def load_symbols( self ):
+        """loads public( shared ) symbols from the binary file.
+
+        This method should be overiden in the derived classes.
+        """
         raise NotImplementedError()
 
-    def merge( self ):
+    def merge( self, symbol):
+        """extracts and merges information from the symbol to the declarations tree.
+
+        This method should be overiden in the derived classes.
+        """
         raise NotImplementedError()
 
     def parse( self ):
+        """main class method
+
+        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.
+        """
         self.__loaded_symbols = self.load_symbols()
         result = {}
         for smbl in self.__loaded_symbols:
@@ -73,6 +102,7 @@
 CCTS = declarations.CALLING_CONVENTION_TYPES
 
 class msvc_libparser_t( libparser_t ):
+    """base parser class for few MSVC binary files"""
     def __init__( self, global_ns, binary_file ):
         libparser_t.__init__( self, global_ns, binary_file )
         self.__formated_decls = {}
@@ -89,6 +119,7 @@
         return self.__formated_decls
 
 class map_file_parser_t( msvc_libparser_t ):
+    """parser for MSVC .map file"""
     c_entry = re.compile( r' +\d+    (?P<internall>.+?)(?:\s+exported name\:\s(?P<name>.*)$)')
     cpp_entry = re.compile( r' +\d+    (?P<decorated>.+?) \((?P<undecorated>.+)\)$' )
 
@@ -145,6 +176,7 @@
 
 
 class dll_file_parser_t( msvc_libparser_t ):
+    """parser for Windows .dll file"""
     def __init__( self, global_ns, map_file_path ):
         global dll_file_parser_warning
         warnings.warn( dll_file_parser_warning, LicenseWarning )
@@ -172,8 +204,9 @@
                 decl.calling_convention = CCTS.extract( blob_undecorated, CCTS.CDECL )
             return blob, decl
 
-
 def merge_information( global_ns, fname, runs_under_unittest=False ):
+    """high level function - select the appropriate binary file parser and integrates
+    the information from the file to the declarations tree. """
     ext = os.path.splitext( fname )[1]
     parser = None
     if '.dll' == ext:

Modified: pygccxml_dev/pygccxml/binary_parsers/undname.py
===================================================================
--- pygccxml_dev/pygccxml/binary_parsers/undname.py	2009-01-06 10:02:45 UTC (rev 1540)
+++ pygccxml_dev/pygccxml/binary_parsers/undname.py	2009-01-06 13:06:23 UTC (rev 1541)
@@ -3,6 +3,10 @@
 # accompanying file LICENSE_1_0.txt or copy at
 # http://www.boost.org/LICENSE_1_0.txt)
 
+"""
+provides functionality needed to undecorate\demangle compiler generated unique names
+"""
+
 import os
 import re
 import sys


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.