Refactor:core:Document navit_object_attr_get()

Signed-off-by: mvglasow <michael -at- vonglasow.com>

1 files changed, 25 insertions, 0 deletions

diff --git a/navit/xmlconfig.c b/navit/xmlconfig.c
index 66b73fd02..f752998eb 100644
--- a/navit/xmlconfig.c
+++ b/navit/xmlconfig.c
@@ -1295,6 +1295,31 @@ navit_object_attr_iter_destroy(struct attr_iter *iter)
 	g_free(iter);
 }
 
+/**
+ * @brief Generic get function
+ *
+ * This function searches an attribute list for an attribute of a given type and stores it in the {@code attr}
+ * parameter. Internally it calls
+ * {@link attr_generic_get_attr(struct attr **, struct attr **, enum attr_type, struct attr *, struct attr_iter *)}
+ * to retrieve the attribute; see its documentation for details.
+ * <p>
+ * Searching for attr_any or attr_any_xml is supported.
+ * <p>
+ * An iterator can be specified to get multiple attributes of the same type:
+ * The first call will return the first match; each subsequent call
+ * with the same iterator will return the next match. If no more matching
+ * attributes are found in either of them, false is returned.
+ *
+ * @param obj The object to return an attribute for. This can be any Navit object type, but the parameter should
+ * be cast to {@code struct navit_object *} to avoid compiler warnings.
+ * @param type The attribute type to search for. Searching for {@code attr_any} or {@code attr_any_xml} is
+ * possible.
+ * @param attr Points to a {@code struct attr} which will receive the attribute
+ * @param iter An iterator to receive multiple attributes of the same type with subsequent calls. If {@code NULL},
+ * the first matching attribute will be retrieved.
+ *
+ * @return True if a matching attribute was found, false if not.
+ */
 int
 navit_object_get_attr(struct navit_object *obj, enum attr_type type, struct attr *attr, struct attr_iter *iter)
 {