Comments cleanup, deleted Markdown._processTree function.

1 files changed, 60 insertions, 48 deletions

diff --git a/markdown.py b/markdown.py
index a39a99c..f64fd16 100755
--- a/markdown.py
+++ b/markdown.py
@@ -53,11 +53,11 @@ def message(level, text):
     logger.log(level, text)
     
 def isstr(s):
+    """ Check if it's string """
     return isinstance(s, unicode) or isinstance(s, str)
  
 def importETree(): 
-    """ Imports best variant of ElementTree
-     and returns module object """
+    """ Import best variant of ElementTree and return module object """
     cetree = None  
     try:
         # Python 2.5+
@@ -96,6 +96,7 @@ def importETree():
 etree = importETree()
 
 def indentETree(elem, level=0):
+    """ Indent ElementTree before serialization """
      
     if level > 1:
         i = "\n" + (level-1) * "  "
@@ -187,7 +188,7 @@ def isBlockLevel (tag):
 
 
 def codepoint2name(code):
-    """ Returns entity definition by code, or code 
+    """ Return entity definition by code, or code 
     if there is no such entity definition"""
     entity = htmlentitydefs.codepoint2name.get(code)
     if entity:
@@ -196,7 +197,7 @@ def codepoint2name(code):
         return "%s#%d;" % (AND_SUBSTITUTE, code)
     
 def handleAttributes(text, parent):
-        
+    """ Handale attributes, e.g {@id=123} """
     def attributeCallback(match):
         parent.set(match.group(1), match.group(2))
 
@@ -626,7 +627,7 @@ class BacktickPattern (Pattern):
 class DoubleTagPattern (SimpleTagPattern): 
     """ 
     Return a ElementTree element nested in tag2 nested in tag1. 
-    Usefull for strong emphasis etc.
+    Useful for strong emphasis etc.
 
     """
     def handleMatch(self, m):
@@ -849,7 +850,7 @@ class Postprocessor:
         """
         Subclasses of Postprocessor should implement a `run` method, which
         takes a root Element. Method can return another Element, and global
-        root Element will be replaced, or just mnodify current and return None.
+        root Element will be replaced, or just modify current and return None.
         """
         pass
 
@@ -870,7 +871,7 @@ class TextPostprocessor:
         """
         Subclasses of TextPostprocessor should implement a `run` method, which
         takes the html document as a single text string and returns a 
-        (possably modified) string.
+        (possibly modified) string.
 
         """
         pass
@@ -1059,20 +1060,31 @@ def dequote(string):
 class InlineStash:
     
     def __init__(self):
+        """ Create a InlineStash. """
         self.prefix = INLINE_PLACEHOLDER_PREFIX
         self.suffix = INLINE_PLACEHOLDER_SUFFIX
         self._nodes = {}
         self.phLength = 4 + len(self.prefix) + len(self.suffix)
         
     def _genPlaceholder(self, type):
-        """ Generates placeholder """
+        """ Generate a placeholder """
         id = "%04d" % len(self._nodes)
         hash = "%s%s:%s%s" % (self.prefix, type, id, 
                                 self.suffix) 
         return hash, id
     
     def extractId(self, data, index):
-        """ Extracting id from data string, starting from index """
+        """ 
+        Extract id from data string, start from index
+        
+        Keyword arguments:
+        
+        * data: string
+        * index: index, from which we start search 
+        
+        Returns: placeholder id and  string index, after 
+        found placeholder
+        """
         endIndex = data.find(self.suffix, index+1)
         if endIndex == -1:
             return None, index + 1 
@@ -1087,15 +1099,17 @@ class InlineStash:
         return self._nodes.has_key(id)
     
     def get(self, id):
-        """ Returns node by id """
+        """ Return node by id """
         return self._nodes.get(id)
     
     def add(self, node, type):
+        """ Add node to stash """
         pholder, id = self._genPlaceholder(type)
         self._nodes[id] = node
         return pholder
     
     def rest(self):
+        """ Reset instance """
         self._nodes = {}
     
 """
@@ -1633,7 +1647,7 @@ class Markdown:
         
     def _handleInline(self, data, patternIndex=0):
         """
-        Processinf string with inline patterns and replasing it
+        Process string with inline patterns and replace it
         with placeholders
 
         Keyword arguments:
@@ -1641,7 +1655,7 @@ class Markdown:
         * data: A line of Markdown text
         * patternIndex: The index of the inlinePattern to start with
         
-        Return: String with placeholders. 
+        Returns: String with placeholders. 
         
         """
         startIndex = 0
@@ -1659,19 +1673,17 @@ class Markdown:
     
     def _applyInline(self, pattern, data, patternIndex, startIndex=0):
         """ 
-        Given a pattern name, this function checks if the line
-        fits the pattern, creates the necessary elements, adds it 
-        to InlineStash, and returns string with placeholders,
-        instead of ElementTree elements.
+        Check if the line fits the pattern, create the necessary 
+        elements, add it to InlineStash
         
         Keyword arguments:
         
         * data: the text to be processed
         * pattern: the pattern to be checked
         * patternIndex: index of current pattern
-        * startIndex: string index, from wich we starting search
+        * startIndex: string index, from which we starting search
 
-        Returns: String with placeholders.
+        Returns: String with placeholders instead of ElementTree elements.
         """
         match = pattern.getCompiledRegExp().match(data[startIndex:])
         leftData = data[:startIndex]
@@ -1703,7 +1715,19 @@ class Markdown:
                              pholder, match.groups()[-1]), True, 0
    
     def _processElementText(self, node, subnode, isText=True):
+        """
+        Process placeholders in Element.text or Element.tail
+        of Elements popped from InlineStash
+        
+        Keywords arguments:
+        
+        * node: parent node
+        * subnode: processing node
+        * isText: bool variable, True - it's text, False - it's tail
         
+        Returns: None
+        
+        """       
         if isText:
             text = subnode.text
             subnode.text = None
@@ -1725,9 +1749,12 @@ class Markdown:
     
     def _processPlaceholders(self, data, parent):
         """
-        Processes string with placeholders and generates ElementTree tree.
+        Process string with placeholders and generate ElementTree tree.
+        
+        Keyword arguments:
         
         * data: string with placeholders instead of ElementTree elements.
+        * parent: Element, which contains processing inline data
 
         Returns: list with ElementTree elements with applied inline patterns.
         """
@@ -1796,18 +1823,22 @@ class Markdown:
                 data = ""
 
         return result
-        
-    def _processTree(self, el):
+    
+    
+    def applyInlinePatterns(self, markdownTree):
         """
-        Processing ElementTree, and applying inline patterns
+        Iterate over ElementTree, find elements with inline tag, 
+        apply inline patterns and append newly created Elements to tree 
         
         Keyword arguments:
         
-        * el - parent element of ElementTree.
+        * markdownTree: ElementTree object, representing Markdown tree.
 
         Returns: ElementTree object with applied inline patterns.
         """
-
+ 
+        el = markdownTree.getroot()
+                
         stack = [el]
 
         while stack:
@@ -1844,32 +1875,15 @@ class Markdown:
                                                          newChild)
                     currElement.insert(pos, newChild)
                     pos += 1 
-
-
-    def applyInlinePatterns(self, markdownTree):
-        """
-        Retrun ElementTree, with applied
-        inline paterns
-        
-        Keyword arguments:
-        
-        * markdownTree: ElementTree object, reppresenting Markdown tree.
-
-        Returns: ElementTree object.
-        """
- 
-        el = markdownTree.getroot()
-                
-        self._processTree(el)
             
         return markdownTree
 
         
     def markdownToTree(self, source=None):
         """
-        Retrun ElementTree, without applying inline paterns, 
-        all data, that should be processed with
-        inline patterns included in <inline></inline> sections.
+        Create ElementTree, without applying inline paterns, 
+        all data, include all data, that must be procesed wit inline 
+        patterns in <inline></inline> sections.
         
         Keyword arguments:
         
@@ -1903,13 +1917,11 @@ class Markdown:
         
         markdownTree = self._transform()
         
-        return markdownTree
-        
-        
+        return markdownTree      
 
     def convert (self, source=None):
         """
-        Return the document in XHTML format.
+        Create the document in XHTML format.
 
         Keyword arguments: