Refactor:core:Add documentation

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

3 files changed, 40 insertions, 0 deletions

diff --git a/navit/attr.c b/navit/attr.c
index 7eff92fb8..ea907b411 100644
--- a/navit/attr.c
+++ b/navit/attr.c
@@ -681,6 +681,10 @@ attr_generic_prepend_attr(struct attr **attrs, struct attr *attr) {
  *
  * If `attrs` does not contain `attr`, this function is a no-op.
  *
+ * Attributes are matched based on their `type` and `u.data` members, thus `attr` can be a shallow copy
+ * of the attribute, and can match multiple attributes in the list. The `attr` argument itself is not
+ * changed.
+ *
  * @param attrs The attribute list
  * @param attr The attribute to remove from the list
  *
diff --git a/navit/navit.c b/navit/navit.c
index 9cc265b94..709bcb58a 100644
--- a/navit/navit.c
+++ b/navit/navit.c
@@ -1691,6 +1691,22 @@ void navit_set_destinations(struct navit *this_, struct pcoord *c, int count, co
         navit_draw(this_);
 }
 
+/**
+ * @brief Retrieves destinations from the route
+ *
+ * Prior to calling this method, you may want to retrieve the number of destinations by calling
+ * {@link navit_get_destination_count(struct navit *)} and assigning a buffer of sufficient capacity.
+ *
+ * If the return value equals `count`, the buffer was either just large enough or too small to hold the
+ * entire list of destinations; there is no way to tell from the result which is the case.
+ *
+ * If the Navit instance does not have a route, the result is 0.
+ *
+ * @param this_ The Navit instance
+ * @param pc Pointer to an array of projected coordinates which will receive the destination coordinates
+ * @param count Capacity of `pc`
+ * @return The number of destinations stored in `pc`, never greater than `count`
+ */
 int navit_get_destinations(struct navit *this_, struct pcoord *pc, int count) {
     if(!this_->route)
         return 0;
@@ -1698,6 +1714,12 @@ int navit_get_destinations(struct navit *this_, struct pcoord *pc, int count) {
 
 }
 
+/**
+ * @brief Get the destinations count for the route
+ *
+ * @param this The Navit instance
+ * @return destination count for the route, or 0 if the Navit instance has no route
+ */
 int navit_get_destination_count(struct navit *this_) {
     if(!this_->route)
         return 0;
diff --git a/navit/route.c b/navit/route.c
index 652ae6d54..e0358db66 100644
--- a/navit/route.c
+++ b/navit/route.c
@@ -1129,6 +1129,20 @@ void route_set_destinations(struct route *this, struct pcoord *dst, int count, i
     profile(0,"end");
 }
 
+/**
+ * @brief Retrieves destinations from the route
+ *
+ * Prior to calling this method, you may want to retrieve the number of destinations by calling
+ * {@link route_get_destination_count(struct route *)} and assigning a buffer of sufficient capacity.
+ *
+ * If the return value equals `count`, the buffer was either just large enough or too small to hold the
+ * entire list of destinations; there is no way to tell from the result which is the case.
+ *
+ * @param this The route instance
+ * @param pc Pointer to an array of projected coordinates which will receive the destination coordinates
+ * @param count Capacity of `pc`
+ * @return The number of destinations stored in `pc`, never greater than `count`
+ */
 int route_get_destinations(struct route *this, struct pcoord *pc, int count) {
     int ret=0;
     GList *l=this->destinations;