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

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

Revision: 1619
          http://pygccxml.svn.sourceforge.net/pygccxml/?rev=1619&view=rev
Author:   roman_yakovenko
Date:     2009-01-26 10:59:16 +0000 (Mon, 26 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-26 10:40:12 UTC (rev 1618)
+++ pygccxml_dev/pygccxml/binary_parsers/__init__.py	2009-01-26 10:59:16 UTC (rev 1619)
@@ -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 )

Modified: pygccxml_dev/pygccxml/binary_parsers/parsers.py
===================================================================
--- pygccxml_dev/pygccxml/binary_parsers/parsers.py	2009-01-26 10:40:12 UTC (rev 1618)
+++ pygccxml_dev/pygccxml/binary_parsers/parsers.py	2009-01-26 10:59:16 UTC (rev 1619)
@@ -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 @@
         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 @@
 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 @@
 
 
 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'

Modified: pygccxml_dev/pygccxml/binary_parsers/undname.py
===================================================================
--- pygccxml_dev/pygccxml/binary_parsers/undname.py	2009-01-26 10:40:12 UTC (rev 1618)
+++ pygccxml_dev/pygccxml/binary_parsers/undname.py	2009-01-26 10:59:16 UTC (rev 1619)
@@ -58,7 +58,9 @@
     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


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