From d42a606b99816b034a1dfd34905bedfcae6ac774 Mon Sep 17 00:00:00 2001
From: jules <jules@rawmaterialsoftware.com>
Date: Wed, 20 Aug 2014 20:59:31 +0100
Subject: [PATCH] Tried to improve the explanation for
 XmlElement::findParentElementOf.

---
 modules/juce_core/xml/juce_XmlElement.cpp |  2 +-
 modules/juce_core/xml/juce_XmlElement.h   | 13 ++++++++++---
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/modules/juce_core/xml/juce_XmlElement.cpp b/modules/juce_core/xml/juce_XmlElement.cpp
index 000df15d5f..0a9f0543af 100644
--- a/modules/juce_core/xml/juce_XmlElement.cpp
+++ b/modules/juce_core/xml/juce_XmlElement.cpp
@@ -714,7 +714,7 @@ bool XmlElement::isEquivalentTo (const XmlElement* const other,
             {
                 if (thisAtt == nullptr || otherAtt == nullptr)
                 {
-                    if (thisAtt == otherAtt) // both 0, so it's a match
+                    if (thisAtt == otherAtt) // both nullptr, so it's a match
                         break;
 
                     return false;
diff --git a/modules/juce_core/xml/juce_XmlElement.h b/modules/juce_core/xml/juce_XmlElement.h
index 4ab4d0886e..2f03e93aa6 100644
--- a/modules/juce_core/xml/juce_XmlElement.h
+++ b/modules/juce_core/xml/juce_XmlElement.h
@@ -599,10 +599,17 @@ public:
     /** Returns true if the given element is a child of this one. */
     bool containsChildElement (const XmlElement* possibleChild) const noexcept;
 
-    /** Recursively searches all sub-elements to find one that contains the specified
-        child element.
+    /** Recursively searches all sub-elements of this one, looking for an element
+        which is the direct parent of the specified element.
+
+        Because elements don't store a pointer to their parent, if you have one
+        and need to find its parent, the only way to do so is to exhaustively
+        search the whole tree for it.
+
+        If the given child is found somewhere in this element's hierarchy, then
+        this method will return its parent. If not, it will return nullptr.
     */
-    XmlElement* findParentElementOf (const XmlElement* elementToLookFor) noexcept;
+    XmlElement* findParentElementOf (const XmlElement* childToSearchFor) noexcept;
 
     //==============================================================================
     /** Sorts the child elements using a comparator.