Fixing docstrings and comments.

arpeggio/export.py

@@ -12,9 +12,9 @@ from arpeggio import Terminal
 
 
 class Export(object):
-    '''
+    """
     Base class for all Exporters.
-    '''
+    """
 
     def __init__(self):
         super(Export, self).__init__()
@@ -30,13 +30,17 @@ class Export(object):
                                         # returned for the same adaptee object
 
     def export(self, obj):
-        '''Export of obj to a string.'''
+        """
+        Export of an obj to a string.
+        """
         self._outf = StringIO()
         self._export(obj)
         return self._outf.getvalue()
 
     def exportFile(self, obj, file_name):
-        '''Export of obj to a file.'''
+        """
+        Export of obj to a file.
+        """
         self._outf = open(file_name, "w")
         self._export(obj)
         self._outf.close()
@@ -47,15 +51,15 @@ class Export(object):
         self._outf.write(self._end())
 
     def _start(self):
-        '''
+        """
         Override this to specify the beginning of the graph representation.
-        '''
+        """
         return ""
 
     def _end(self):
-        '''
+        """
         Override this to specify the end of the graph representation.
-        '''
+        """
         return ""
 
 
@@ -63,12 +67,12 @@ class ExportAdapter(object):
     '''
     Base adapter class for the export support.
     Adapter should be defined for every graph type.
+
+    Attributes:
+        adaptee: A node to adapt.
+        export: An export object used as a context of the export.
     '''
     def __init__(self, node, export):
-        '''
-        @param node - node to adapt
-        @param export - export object used as a context of the export.
-        '''
         self.adaptee = node     # adaptee is adapted graph node
         self.export = export
 
@@ -78,29 +82,35 @@ class ExportAdapter(object):
 
 
 class DOTExportAdapter(ExportAdapter):
-    '''
+    """
     Base adapter class for the DOT export support.
-    '''
+    """
     @property
     def id(self):
-        '''Graph node unique identification.'''
+        """
+        Graph node unique identification.
+        """
         raise NotImplementedError()
 
     @property
     def desc(self):
-        '''Graph node textual description.'''
+        """
+        Graph node textual description.
+        """
         raise NotImplementedError()
 
     @property
     def children(self):
-        '''Children of the graph node.'''
+        """
+        Children of the graph node.
+        """
         raise NotImplementedError()
 
 
 class PMDOTExportAdapter(DOTExportAdapter):
-    '''
+    """
     Adapter for ParsingExpression graph types (parser model).
-    '''
+    """
     @property
     def id(self):
         return id(self.adaptee)
@@ -133,9 +143,9 @@ class PMDOTExportAdapter(DOTExportAdapter):
 
 
 class PTDOTExportAdapter(PMDOTExportAdapter):
-    '''
+    """
     Adapter for ParseTreeNode graph types.
-    '''
+    """
     @property
     def children(self):
         if isinstance(self.adaptee, Terminal):
@@ -150,9 +160,9 @@ class PTDOTExportAdapter(PMDOTExportAdapter):
 
 
 class DOTExport(Export):
-    '''
+    """
     Export to DOT language (part of GraphViz, see http://www.graphviz.org/)
-    '''
+    """
     def _render_node(self, node):
         if not node in self._render_set:
             self._render_set.add(node)
@@ -183,9 +193,9 @@ class DOTExport(Export):
 
 
 class PMDOTExport(DOTExport):
-    '''
-    Convenience DOTExport extension that uses ParserExpressionDOTExportAdapter
-    '''
+    """
+    A convenience DOTExport extension that uses ParserExpressionDOTExportAdapter
+    """
     def export(self, obj):
         return super(PMDOTExport, self).\
             export(PMDOTExportAdapter(obj, self))
@@ -196,9 +206,9 @@ class PMDOTExport(DOTExport):
 
 
 class PTDOTExport(DOTExport):
-    '''
-    Convenience DOTExport extension that uses PTDOTExportAdapter
-    '''
+    """
+    A convenience DOTExport extension that uses PTDOTExportAdapter
+    """
     def export(self, obj):
         return super(PTDOTExport, self).\
             export(PTDOTExportAdapter(obj, self))

examples/bibtex.py

@@ -26,7 +26,9 @@ def comment():          return _(r'[^@]+')
 
 # Semantic actions
 class BibFileSem(SemanticAction):
-    '''Just returns list of child nodes (bibentries).'''
+    """
+    Just returns list of child nodes (bibentries).
+    """
     def first_pass(self, parser, node, nodes):
         if parser.debug:
             print "Processing Bibfile"
@@ -34,8 +36,10 @@ class BibFileSem(SemanticAction):
 
 
 class BibEntrySem(SemanticAction):
-    '''Constructs a map where key is bibentry field name.
-        Key is returned under 'bibkey' key. Type is returned under 'bibtype'.'''
+    """
+    Constructs a map where key is bibentry field name.
+    Key is returned under 'bibkey' key. Type is returned under 'bibtype'.
+    """
     def first_pass(self, parser, node, nodes):
         if parser.debug:
             print "  Processing bibentry %s" % nodes[2]
@@ -50,7 +54,9 @@ class BibEntrySem(SemanticAction):
 
 
 class FieldSem(SemanticAction):
-    '''Constructs a tuple (fieldname, fieldvalue).'''
+    """
+    Constructs a tuple (fieldname, fieldvalue).
+    """
     def first_pass(self, parser, node, nodes):
         if parser.debug:
             print "    Processing field %s" % nodes[0]
@@ -59,7 +65,9 @@ class FieldSem(SemanticAction):
 
 
 class FieldValueSem(SemanticAction):
-    '''Serbian Serbian letters form latex encoding to Unicode.'''
+    """
+    Serbian Serbian letters form latex encoding to Unicode.
+    """
     def first_pass(self, parser, node, nodes):
         return node.value.replace(r"\'{c}", u"ć")\
                     .replace(r"\'{C}", u"Ć")\

examples/calc.py

@@ -24,13 +24,17 @@ def calc():       return OneOrMore(expression), EndOfFile
 
 # Semantic actions
 class ToFloat(SemanticAction):
-    '''Converts node value to float.'''
+    """
+    Converts node value to float.
+    """
     def first_pass(self, parser, node, nodes):
         print "Converting %s." % node.value
         return float(node.value)
 
 class Factor(SemanticAction):
-    '''Removes parenthesis if exists and returns what was contained inside.'''
+    """
+    Removes parenthesis if exists and returns what was contained inside.
+    """
     def first_pass(self, parser, node, nodes):
         print "Factor %s" % nodes
         if len(nodes) == 1:
@@ -45,10 +49,10 @@ class Factor(SemanticAction):
             return sign * nodes[next]
 
 class Term(SemanticAction):
-    '''
+    """
     Divides or multiplies factors.
     Factor nodes will be already evaluated.
-    '''
+    """
     def first_pass(self, parser, node, nodes):
         print "Term %s" % nodes
         term = nodes[0]
@@ -61,10 +65,10 @@ class Term(SemanticAction):
         return term
 
 class Expr(SemanticAction):
-    '''
+    """
     Adds or substracts terms.
     Term nodes will be already evaluated.
-    '''
+    """
     def first_pass(self, parser, node, nodes):
         print "Expression %s" % nodes
         expr = 0

examples/calc_peg.py

@@ -27,7 +27,7 @@ calc_grammar = """
                   (number / "(" expression ")");
         term <- factor (( "*" / "/") factor)*;
         expression <- term (("+" / "-") term)*;
-        calc <- expression EndOfFile;
+        calc <- expression+ EndOfFile;
 """
 
 # Rules are mapped to semantic actions

examples/json.py

@@ -5,7 +5,7 @@
 # Copyright: (c) 2009 Igor R. Dejanovic <igor DOT dejanovic AT gmail DOT com>
 # License: MIT License
 #
-# This example is based on jsonParser.py from pyparsing project
+# This example is based on jsonParser.py from the pyparsing project
 # (see http://pyparsing.wikispaces.com/).
 ##############################################################################
 

examples/simple.py

@@ -31,8 +31,8 @@ def simpleLanguage():   return function
 
 try:
 
-    # Parser instantiation. simpleLanguage is root definition and comment is
-    # grammar rule for comments.
+    # Parser instantiation. simpleLanguage is the definition of the root rule
+    # and comment is a grammar rule for comments.
     parser = ParserPython(simpleLanguage, comment, debug=True)
 
     # We save parser model to dot file in order to visualise it.