Refactor:core:Improve documentation

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

1 files changed, 11 insertions, 3 deletions

diff --git a/navit/mapset.c b/navit/mapset.c
index a2e914b6b..58751ee1e 100644
--- a/navit/mapset.c
+++ b/navit/mapset.c
@@ -179,11 +179,19 @@ mapset_open(struct mapset *ms) {
 /**
  * @brief Gets the next map from a mapset handle
  *
- * If you set active to true, this function will not return any maps that
- * have the attr_active attribute associated with them and set to false.
+ * The `active` argument governs whether (and how) to limit the search to active maps:
+ *
+ * Passing 0 causes this function to cycle through all maps, whether active or not.
+ *
+ * Passing a value of 2 will return only maps which have the `attr_route_active` attribute set to true.
+ *
+ * Passing a value of 3 will return only maps which have the `attr_search_active` attribute set to true.
+ *
+ * Passing any other nonzero value will return only maps which have the `attr_active` attribute set to true,
+ * or not set at all.
  *
  * @param msh The mapset handle to get the next map of
- * @param active Set to true to only get active maps (See description)
+ * @param active Whether to cycle only through active maps (see description)
  * @return The next map
  */
 struct map * mapset_next(struct mapset_handle *msh, int active) {