* Lots of documentation for the Inkscape::XML namespace

[inkscape.git] / src / xml / repr-util.cpp

diff --git a/src/xml/repr-util.cpp b/src/xml/repr-util.cpp
index 59563a7fc754f8a6d9c3a55b67a30b1aac283ffa..528902fef6505edc8609b29262f960465be0a5cf 100644 (file)
--- a/src/xml/repr-util.cpp
+++ b/src/xml/repr-util.cpp
@@ -344,6 +344,7 @@ long long int sp_repr_get_int_attribute(Inkscape::XML::Node *repr, char const *k
  *    0    positions are equivalent
  *    1    first object's position is greater than the second
  *   -1    first object's position is less than the second
+ * @todo Rewrite this function's description to be understandable
  */
 int
 sp_repr_compare_position(Inkscape::XML::Node *first, Inkscape::XML::Node *second)
@@ -397,7 +398,15 @@ sp_repr_compare_position(Inkscape::XML::Node *first, Inkscape::XML::Node *second
 }
 
 /**
- * lookup child by \a key, \a value.
+ * @brief Find an element node using an unique attribute
+ *
+ * This function returns the first child of the specified node that has the attribute
+ * @c key equal to @c value. Note that this function does not recurse.
+ *
+ * @param repr The node to start from
+ * @param key The name of the attribute to use for comparisons
+ * @param value The value of the attribute to look for
+ * @relatesalso Inkscape::XML::Node
  */
 Inkscape::XML::Node *
 sp_repr_lookup_child(Inkscape::XML::Node *repr,
@@ -417,11 +426,16 @@ sp_repr_lookup_child(Inkscape::XML::Node *repr,
 }
 
 /**
- *  \brief   Recursively find the Inkscape::XML::Node matching the given XML name.
- *  \return  A pointer to the matching Inkscape::XML::Node
- *  \param   repr    The Inkscape::XML::Node to start from
- *  \param   name    The desired XML name
- *  
+ * @brief Find an element node with the given name
+ *
+ * This function searches the descendants of the specified node depth-first for
+ * the first XML node with the specified name.
+ *
+ * @param repr The node to start from
+ * @param name The name of the element node to find
+ * @param maxdepth Maximum search depth, or -1 for an unlimited depth
+ * @return  A pointer to the matching Inkscape::XML::Node
+ * @relatesalso Inkscape::XML::Node
  */
 Inkscape::XML::Node *
 sp_repr_lookup_name( Inkscape::XML::Node *repr, gchar const *name, gint maxdepth )