# HG changeset patch
# User cmlenz
# Date 1185184244 0
# Node ID b00765a115a5d70bff8d9f98a597ed48a42f1bec
# Parent  d2e7fc3673842d1cef26ffdd0cf3d801056fd45d
Improve docs on `Stream.select()` for #135.

diff --git a/genshi/core.py b/genshi/core.py
--- a/genshi/core.py
+++ b/genshi/core.py
@@ -166,6 +166,27 @@
         """Return a new stream that contains the events matching the given
         XPath expression.
         
+        >>> from genshi import HTML
+        >>> stream = HTML('<doc><elem>foo</elem><elem>bar</elem></doc>')
+        >>> print stream.select('elem')
+        <elem>foo</elem><elem>bar</elem>
+        >>> print stream.select('elem/text()')
+        foobar
+        
+        Note that the outermost element of the stream becomes the *context
+        node* for the XPath test. That means that the expression "doc" would
+        not match anything in the example above, because it only tests against
+        child elements of the outermost element:
+        
+        >>> print stream.select('doc')
+        <BLANKLINE>
+        
+        You can use the "." expression to match the context node itself
+        (although that usually makes little sense):
+        
+        >>> print stream.select('.')
+        <doc><elem>foo</elem><elem>bar</elem></doc>
+        
         :param path: a string containing the XPath expression
         :param namespaces: mapping of namespace prefixes used in the path
         :param variables: mapping of variable names to values
diff --git a/genshi/filters/html.py b/genshi/filters/html.py
--- a/genshi/filters/html.py
+++ b/genshi/filters/html.py
@@ -321,6 +321,7 @@
         :param uri: the URI to check
         :return: `True` if the URI can be considered safe, `False` otherwise
         :rtype: `bool`
+        :since: version 0.4.3
         """
         if ':' not in uri:
             return True # This is a relative URI
@@ -354,6 +355,7 @@
                      contain any character or numeric references
         :return: a list of declarations that are considered safe
         :rtype: `list`
+        :since: version 0.4.3
         """
         decls = []
         text = self._strip_css_comments(self._replace_unicode_escapes(text))
diff --git a/genshi/filters/i18n.py b/genshi/filters/i18n.py
--- a/genshi/filters/i18n.py
+++ b/genshi/filters/i18n.py
@@ -11,7 +11,10 @@
 # individuals. For the exact contribution history, see the revision
 # history and logs, available at http://genshi.edgewall.org/log/.
 
-"""Utilities for internationalization and localization of templates."""
+"""Utilities for internationalization and localization of templates.
+
+:since: version 0.4
+"""
 
 from compiler import ast
 try:
@@ -321,7 +324,10 @@
 
 
 class MessageBuffer(object):
-    """Helper class for managing localizable mixed content."""
+    """Helper class for managing localizable mixed content.
+    
+    :since: version 0.5
+    """
 
     def __init__(self, lineno=-1):
         self.lineno = lineno
@@ -385,6 +391,7 @@
     :param code: the `Code` object
     :type code: `genshi.template.eval.Code`
     :param gettext_functions: a sequence of function names
+    :since: version 0.5
     """
     def _walk(node):
         if isinstance(node, ast.CallFunc) and isinstance(node.node, ast.Name) \
@@ -421,6 +428,8 @@
     
     >>> parse_msg("[1:] Bilder pro Seite anzeigen.")
     [(1, ''), (0, ' Bilder pro Seite anzeigen.')]
+    
+    :since: version 0.5
     """
     parts = []
     stack = [0]
diff --git a/genshi/filters/transform.py b/genshi/filters/transform.py
--- a/genshi/filters/transform.py
+++ b/genshi/filters/transform.py
@@ -43,6 +43,8 @@
 
 The ``Transformer`` support a large number of useful transformations out of the
 box, but custom transformations can be added easily.
+
+:since: version 0.5
 """
 
 import re