aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorWaylan Limberg <waylan.limberg@icloud.com>2014-12-29 11:39:00 -0500
committerWaylan Limberg <waylan.limberg@icloud.com>2014-12-29 11:39:00 -0500
commit257c0fe9aad40879ebe9b6e84613d5c3a5adf2b5 (patch)
tree5502de661d18271ec2469700328d7554a86eb64d
parentfad98e502accac6a0aba27b4d15266b0554e9ad1 (diff)
downloadmarkdown-257c0fe9aad40879ebe9b6e84613d5c3a5adf2b5.tar.gz
markdown-257c0fe9aad40879ebe9b6e84613d5c3a5adf2b5.tar.bz2
markdown-257c0fe9aad40879ebe9b6e84613d5c3a5adf2b5.zip
Better docs of treeprocessor API.
Fixes #375. Explains the difference between returning None and returning a modified root element. Also makes the docs more consistent with the doc strings in the code.
-rw-r--r--docs/extensions/api.txt17
1 files changed, 14 insertions, 3 deletions
diff --git a/docs/extensions/api.txt b/docs/extensions/api.txt
index 8837818..7987c25 100644
--- a/docs/extensions/api.txt
+++ b/docs/extensions/api.txt
@@ -136,7 +136,8 @@ the tree and runs the InlinePatterns on the text of each Element in the tree.
A Treeprocessor should inherit from ``markdown.treeprocessors.Treeprocessor``,
over-ride the ``run`` method which takes one argument ``root`` (an Elementree
-object) and returns either that root element or a modified root element.
+object) and either modifies that root element and returns `None` or returns a
+new ElementTree object.
A pseudo example:
@@ -144,8 +145,18 @@ A pseudo example:
class MyTreeprocessor(Treeprocessor):
def run(self, root):
- #do stuff
- return my_modified_root
+ root.text = 'modified content'
+
+Note that Python class methods return `None` by default when no `return`
+statement is defined. Additionly all Python variables refer to objects by
+reference. Therefore, the above `run` method modifies the `root` element
+in place and returns `None`. The changes made to the `root` element and its
+children are retained.
+
+Some may be inclined to return the modified `root` element. While that would
+work, it would cause a copy of the entire ElemetTree to be generated each
+time the treeprocessor is run. Therefore, it is generally expected that
+the `run` method would only return `None` or a new ElementTree object.
For specifics on manipulating the ElementTree, see
[Working with the ElementTree][] below.