From d16ac3518d6b8d5fdc61a9cf3d33c9057190c115 Mon Sep 17 00:00:00 2001
From: Waylan Limberg <waylan@gmail.com>
Date: Tue, 11 Mar 2008 00:15:53 +0000
Subject: Added docstrings to all root level functions.

---
 markdown.py | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 63 insertions(+), 4 deletions(-)

diff --git a/markdown.py b/markdown.py
index d74d2de..e0e6bba 100644
--- a/markdown.py
+++ b/markdown.py
@@ -9,7 +9,7 @@ Converts Markdown to HTML.  Basic usage as a module:
     md = Markdown()
     html = md.convert(your_text_string)
 
-See http://www.freewisdom.org/projects/python-markdown/ for more
+See <http://www.freewisdom.org/projects/python-markdown/> for more
 information and instructions on how to extend the functionality of the
 script.  (You might want to read that before you try modifying this
 file.)
@@ -84,6 +84,11 @@ BOMS = { 'utf-8': (codecs.BOM_UTF8, ),
          }
 
 def removeBOM(text, encoding):
+    """
+    Used by `markdownFromFile` to remove a "byte order mark" from the begining
+    of an utf-8, utf-16 or utf-32 encoded file.
+    """
+    
     convert = isinstance(text, unicode)
     for bom in BOMS[encoding]:
         bom = convert and bom.decode(encoding) or bom
@@ -111,6 +116,10 @@ BLOCK_LEVEL_ELEMENTS = ['p', 'div', 'blockquote', 'pre', 'table',
                         'del', 'hr', 'hr/', 'style']
 
 def isBlockLevel (tag):
+    """
+    Used by HTMLBlockPreprocessor to check if a given tag is a block level 
+    element.
+    """
     return ( (tag in BLOCK_LEVEL_ELEMENTS) or
              (tag[0] == 'h' and tag[1] in "0123456789") )
 
@@ -138,6 +147,9 @@ ENTITY_NORMALIZATION_EXPRESSIONS_SOFT = [ (re.compile("&(?!\#)"), "&amp;"),
 
 
 def getBidiType(text):
+    """
+    Get Bi-directional text type. Used by TextNode to determine text direction.
+    """
 
     if not text: return None
 
@@ -1817,6 +1829,7 @@ class Markdown:
 
     def __str__(self):
         ''' Report info about instance. Markdown always returns unicode. '''
+
         if self.source is None:
             status = 'in which no source text has been assinged.'
         else:
@@ -1838,6 +1851,29 @@ def markdownFromFile(input = None,
                      encoding = None,
                      message_threshold = CRITICAL,
                      safe = False):
+    """
+    Convenience wrapper function that takes a filename as input.
+
+    Used from the command-line, although may be useful in other situations. 
+    Decodes the file using the provided encoding (defaults to utf-8), passes 
+    the file content to markdown, and outputs the html to either the provided
+    filename or stdout in the same encoding as the source file.
+
+    **Note:** This is the only place that decoding and encoding takes place
+    in Python-Markdown.
+
+    Keyword arguments:
+
+    * input: Name of source text file.
+    * output: Name of output file. Writes to stdout if `None`.
+    * extensions: A list of extension names (may contain config args).  
+    * encoding: Encoding of input and output files. Defaults to utf-8.
+    * message_threshold: Error reporting level.
+    * safe_mode: Disallow raw html. One of "remove", "replace" or "escape".
+
+    Returns: An HTML document as a string.
+
+    """
 
     global console_hndlr
     console_hndlr.setLevel(message_threshold)
@@ -1866,7 +1902,21 @@ def markdownFromFile(input = None,
 def markdown(text,
              extensions = [],
              safe_mode = False):
-    
+    """
+    Convenience wrapper function for `Markdown` class.
+
+    Useful in a typical use case. Initializes an instance of the `Markdown` 
+    class, loads any extensions and runs the parser on the given text. 
+
+    Keyword arguments:
+
+    * text: An ascii or Unicode string of Markdown formatted text.
+    * extensions: A list of extension names (may contain config args).  
+    * safe_mode: Disallow raw html. One of "remove", "replace" or "escape".
+
+    Returns: An HTML document as a string.
+
+    """
     message(DEBUG, "in markdown.markdown(), received text:\n%s" % text)
 
     extensions = [load_extension(e) for e in extensions]
@@ -1897,8 +1947,13 @@ class Extension:
 
 def load_extension(ext_name, configs = []):
     """ 
-    Load extention by name, then return the module.
-    The name may contain arguments.
+    Load extension by name, then return the module.
+    
+    The extension name may contain arguments as part of the string in the 
+    following format:
+
+        "extname(key1=value1,key2=value2)"
+    
     Print an error message and exit on failure. 
     
     """
@@ -1936,6 +1991,10 @@ For lower versions of Python use:
 """ % EXECUTABLE_NAME_FOR_USAGE
 
 def parse_options():
+    """
+    Define and parse `optparse` options for command-line usage.
+    """
+
     try:
         optparse = __import__("optparse")
     except:
-- 
cgit v1.2.3