[svn r3285] r3470@delle: sbehnel | 2008-02-13 20:12:19 +0100

 loads of docstrings

--HG--
branch : trunk

11 files changed, 73 insertions, 11 deletions

diff --git a/src/lxml/ElementInclude.py b/src/lxml/ElementInclude.py
index 725f56f0..d78114c1 100644
--- a/src/lxml/ElementInclude.py
+++ b/src/lxml/ElementInclude.py
@@ -41,9 +41,14 @@
 # OF THIS SOFTWARE.
 # --------------------------------------------------------------------
 
-##
-# Limited XInclude support for the ElementTree package.
-##
+"""
+Limited XInclude support for the ElementTree package.
+
+While lxml.etree has full support for XInclude (see
+`etree.ElementTree.xinclude()`), this module provides a simpler, pure
+Python, ElementTree compatible implementation that supports a simple
+form of custom URL resolvers.
+"""
 
 import copy, etree
 from urlparse import urljoin
diff --git a/src/lxml/builder.py b/src/lxml/builder.py
index b6f205fc..b0088063 100644
--- a/src/lxml/builder.py
+++ b/src/lxml/builder.py
@@ -33,6 +33,10 @@
 # OF THIS SOFTWARE.
 # --------------------------------------------------------------------
 
+"""
+The ``E`` Element factory for generating XML documents.
+"""
+
 import etree as ET
 
 try:
diff --git a/src/lxml/cssselect.py b/src/lxml/cssselect.py
index 5baac589..c4a129c5 100644
--- a/src/lxml/cssselect.py
+++ b/src/lxml/cssselect.py
@@ -1,3 +1,9 @@
+"""CSS Selectors based on XPath.
+
+This module supports selecting XML/HTML tags based on CSS selectors.
+See the `CSSSelector` class for details.
+"""
+
 import re
 from lxml import etree
 
@@ -11,7 +17,17 @@ class ExpressionError(RuntimeError):
     pass
 
 class CSSSelector(etree.XPath):
+    """A CSS selector.
+
+    Usage::
 
+        >>> from lxml import etree, cssselect
+        >>> select = cssselect.CSSSelector("a tag > child")
+
+        >>> root = etree.XML("<a><b><c/><tag><child>TEXT</child></tag></b></a>")
+        >>> [ el.tag for el in select(root) ]
+        ['child']
+    """
     def __init__(self, css):
         path = css_to_xpath(css)
         etree.XPath.__init__(self, path)
@@ -575,9 +591,8 @@ class XPathExpr(object):
         self.condition = other.condition
 
 class XPathExprOr(XPathExpr):
-
     """
-    Represents on |'d expressions.  Note that unfortunately it isn't
+    Represents |'d expressions.  Note that unfortunately it isn't
     the union, it's the sum, so duplicate elements will appear.
     """
 
diff --git a/src/lxml/doctestcompare.py b/src/lxml/doctestcompare.py
index 292b2160..9f388940 100644
--- a/src/lxml/doctestcompare.py
+++ b/src/lxml/doctestcompare.py
@@ -1,8 +1,16 @@
 """
 lxml-based doctest output comparison.
 
-To use this you must call ``lxmldoctest.install()``, which will cause
-doctest to use this in all subsequent calls.
+Note: normally, you should just import the `lxml.usedoctest` and
+`lxml.html.usedoctest` modules from within a doctest, instead of this
+one::
+
+    >>> import lxml.usedoctest # for XML output
+
+    >>> import lxml.html.usedoctest # for HTML output
+
+To use this module directly, you must call ``lxmldoctest.install()``,
+which will cause doctest to use this in all subsequent calls.
 
 This changes the way output is checked and comparisons are made for
 XML or HTML-like content.
diff --git a/src/lxml/html/__init__.py b/src/lxml/html/__init__.py
index 3e000cb9..22ba9143 100644
--- a/src/lxml/html/__init__.py
+++ b/src/lxml/html/__init__.py
@@ -1,3 +1,6 @@
+"""The ``lxml.html`` tool set for HTML handling.
+"""
+
 import threading
 import re
 import urlparse
diff --git a/src/lxml/html/builder.py b/src/lxml/html/builder.py
index 7c62bd16..2230ccef 100644
--- a/src/lxml/html/builder.py
+++ b/src/lxml/html/builder.py
@@ -4,7 +4,7 @@
 # --------------------------------------------------------------------
 
 """
-HTML specialisation of ``builder.py`` by Fredrik Lundh
+A set of HTML generator tags for building HTML documents.
 
 Usage::
 
diff --git a/src/lxml/html/clean.py b/src/lxml/html/clean.py
index 9f7497d4..be6a7a03 100644
--- a/src/lxml/html/clean.py
+++ b/src/lxml/html/clean.py
@@ -1,3 +1,9 @@
+"""A cleanup tool for HTML.
+
+Removes unwanted tags and content.  See the `Cleaner` class for
+details.
+"""
+
 import re
 import copy
 import urlparse
diff --git a/src/lxml/lxml.etree.pyx b/src/lxml/lxml.etree.pyx
index aaee927f..9e412d30 100644
--- a/src/lxml/lxml.etree.pyx
+++ b/src/lxml/lxml.etree.pyx
@@ -1,5 +1,5 @@
-"""The lxml.etree module implements the extended ElementTree API for
-XML.
+"""The ``lxml.etree`` module implements the extended ElementTree API
+for XML.
 """
 
 __docformat__ = "restructuredtext en"
diff --git a/src/lxml/lxml.objectify.pyx b/src/lxml/lxml.objectify.pyx
index 9cc0c990..0e04c38b 100644
--- a/src/lxml/lxml.objectify.pyx
+++ b/src/lxml/lxml.objectify.pyx
@@ -1,3 +1,7 @@
+"""The ``lxml.objectify`` module implements a Python object API for
+XML.  It is based on `lxml.etree`.
+"""
+
 from etreepublic cimport _Document, _Element, ElementBase
 from etreepublic cimport _ElementIterator, ElementClassLookup
 from etreepublic cimport elementFactory, import_lxml__etree, textOf
diff --git a/src/lxml/sax.py b/src/lxml/sax.py
index 7ff62dc2..faca1b34 100644
--- a/src/lxml/sax.py
+++ b/src/lxml/sax.py
@@ -1,3 +1,15 @@
+"""
+SAX-based adapter to copy trees from/to the Python standard library.
+
+Use the `ElementTreeContentHandler` class to build an ElementTree from
+SAX events.
+
+Use the `ElementTreeProducer` class or the `saxify()` function to fire
+the SAX events of an ElementTree against a SAX ContentHandler.
+
+See http://codespeak.net/lxml/sax.html
+"""
+
 from xml.sax.handler import ContentHandler
 import etree
 from etree import ElementTree, SubElement
@@ -220,4 +232,7 @@ class ElementTreeProducer(object):
         return prefix + ':' + local_name
 
 def saxify(element_or_tree, content_handler):
+    """One-shot helper to generate SAX events from an XML tree and fire
+    them against a SAX ContentHandler.
+    """
     return ElementTreeProducer(element_or_tree, content_handler).saxify()
diff --git a/src/lxml/tests/__init__.py b/src/lxml/tests/__init__.py
index 32802e23..85dfe70d 100644
--- a/src/lxml/tests/__init__.py
+++ b/src/lxml/tests/__init__.py
@@ -1,2 +1,4 @@
-# this is a package
+"""
+The lxml test suite for lxml, ElementTree and cElementTree.
+"""