# HG changeset patch
# User paulb
# Date 1123107679 0
# Node ID d2da4b899953667636fd8600125d290aaab99310
# Parent  94e6c78912b0cb214d1856abe52dbc3723cbf06f
[project @ 2005-08-03 22:21:19 by paulb]
Added some docstrings.

diff -r 94e6c78912b0 -r d2da4b899953 libxml2dom/__init__.py
--- a/libxml2dom/__init__.py	Wed Aug 03 22:21:15 2005 +0000
+++ b/libxml2dom/__init__.py	Wed Aug 03 22:21:19 2005 +0000
@@ -361,31 +361,96 @@
     return Document(Node_createDocument(namespaceURI, localName, doctype))
 
 def parse(stream_or_string, html=0):
+
+    """
+    Parse the given 'stream_or_string', where the supplied object can either be
+    a stream (such as a file or stream object), or a string (containing the text
+    of a document). If the optional 'html' parameter is set to a true value, the
+    content to be parsed will be treated as being HTML rather than XML.
+
+    A document object is returned by this function.
+    """
+
     if hasattr(stream_or_string, "read"):
         stream = stream_or_string
         return parseString(stream.read(), html)
     else:
         return parseFile(stream_or_string, html)
 
-def parseFile(s, html=0):
-    return Document(Node_parseFile(s, html))
+def parseFile(filename, html=0):
+
+    """
+    Parse the file having the given 'filename'. If the optional 'html' parameter
+    is set to a true value, the content to be parsed will be treated as being
+    HTML rather than XML.
+
+    A document object is returned by this function.
+    """
+
+    return Document(Node_parseFile(filename, html))
 
 def parseString(s, html=0):
+
+    """
+    Parse the content of the given string 's'. If the optional 'html' parameter
+    is set to a true value, the content to be parsed will be treated as being
+    HTML rather than XML.
+
+    A document object is returned by this function.
+    """
+
     return Document(Node_parseString(s, html))
 
 def parseURI(uri, html=0):
+
+    """
+    Parse the content found at the given 'uri'. If the optional 'html' parameter
+    is set to a true value, the content to be parsed will be treated as being
+    HTML rather than XML.
+
+    A document object is returned by this function.
+    """
+
     return Document(Node_parseURI(uri, html))
 
 def toString(node, encoding=None):
+
+    """
+    Return a string containing the serialised form of the given 'node' and its
+    children. The optional 'encoding' can be used to override the default
+    character encoding used in the serialisation.
+    """
+
     return Node_toString(node.as_native_node(), encoding)
 
 def toStream(node, stream, encoding=None):
+
+    """
+    Write the serialised form of the given 'node' and its children to the given
+    'stream'. The optional 'encoding' can be used to override the default
+    character encoding used in the serialisation.
+    """
+
     Node_toStream(node.as_native_node(), stream, encoding)
 
-def toFile(node, f, encoding=None):
-    Node_toFile(node.as_native_node(), f, encoding)
+def toFile(node, filename, encoding=None):
+
+    """
+    Write the serialised form of the given 'node' and its children to a file
+    having the given 'filename'. The optional 'encoding' can be used to override
+    the default character encoding used in the serialisation.
+    """
+
+    Node_toFile(node.as_native_node(), filename, encoding)
 
 def adoptNodes(nodes):
+
+    """
+    A special utility method which adopts the given low-level 'nodes' and which
+    returns a list of high-level equivalents. This is currently experimental and
+    should not be casually used.
+    """
+
     if len(nodes) == 0:
         return []
     doc = Document(libxml2mod.doc(nodes[0]))