[gxml] Element.vala: Explain some of the tag_name node caching functionality

[Richard Hans Schwarting <rschwart src gnome org>]

commit a279438b8b8f61846d8780b4f7656f63a7250ca0
Author: Richard Schwarting <aquarichy gmail com>
Date:   Wed Nov 21 13:13:04 2012 -0500

    Element.vala: Explain some of the tag_name node caching functionality

 gxml/Element.vala |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)
---
diff --git a/gxml/Element.vala b/gxml/Element.vala
index 3a333f9..1c3ed8e 100644
--- a/gxml/Element.vala
+++ b/gxml/Element.vala
@@ -350,8 +350,13 @@ namespace GXml {
 		  see a, add a, visit a
 		*/
 
+		/* This keeps a list of all descendants with a given tag name, so you can do
+		   elem.get_elements_by_tag_name ("name") and find them quickly; whenever a
+		   node is added to the DOM, all its ancestors have it added to their list */
 		private List<TagNameNodeList> tag_name_lists = new List<TagNameNodeList> ();
 
+		/* Adds a new descendant to this elements cached list of child descendants,
+		   used to isolate the subtree of nodes when filtering by tag name */
 		private void on_new_descendant_with_tag_name (Element elem) {
 			// TODO: consider using a HashTable instead
 			foreach (TagNameNodeList list in tag_name_lists) {