fix:build:fixed compiler warning in graphics modulefix_compiler_warnings

* Update circle.yml

* fix:build:fixed compiler warning in graphics module

* Refactor:core:Add more documentation (#392)

5 files changed, 164 insertions, 12 deletions

diff --git a/circle.yml b/circle.yml
new file mode 100644
index 000000000..e23486c21
--- /dev/null
+++ b/circle.yml
@@ -0,0 +1,48 @@
+machine:
+  environment:
+    CMAKE_FILE: ../Toolchain/arm-eabi.cmake
+dependencies:
+  cache_directories:
+    - ~/.android
+    - ~/android
+    - "~/assets/"
+  pre:
+    - "[ -d ~/assets ] || mkdir ~/assets"
+    - "[ -d ~/android ] || mkdir ~/android"
+    - sudo apt-get update
+    - bash ci/update_version.sh prepare
+# Android build    
+    - sudo apt-get install gettext
+    - sudo apt-get install libsaxonb-java
+# for aapt
+    - sudo apt-get install lib32stdc++6
+    - sudo apt-get install lib32z1
+# For python testing with junit reporting
+    - sudo apt-get install python-gobject libdbus-glib-1-dev python-dev
+    - pip install junit-xml dbus-python
+    - ln -s /usr/lib/python2.7/dist-packages/gobject /opt/circleci/python/2.7.11/lib/python2.7/site-packages/
+    - ln -s /usr/lib/python2.7/dist-packages/glib /opt/circleci/python/2.7.11/lib/python2.7/site-packages/
+test:
+
+  override:
+    - bash ci/build.sh:
+        parallel: true
+        files:
+          - ci/build_android.sh
+deployment:
+  publish_to_playstore:
+    branch: master
+    owner: navit-gps
+    commands:
+      - bash ci/publish.sh
+  merge_into_master:
+    branch: trunk
+    owner: navit-gps
+    commands:
+      - bash ci/update_version.sh push
+      - git push origin $CIRCLE_SHA1:refs/heads/master
+  merge_translations:
+    branch: /i18n.*/
+    owner: navit-gps
+    commands:
+      - bash ci/merge_i18n_update.sh
diff --git a/navit/graphics/gtk_drawing_area/graphics_gtk_drawing_area.c b/navit/graphics/gtk_drawing_area/graphics_gtk_drawing_area.c
index 387003c40..dbb18310a 100644
--- a/navit/graphics/gtk_drawing_area/graphics_gtk_drawing_area.c
+++ b/navit/graphics/gtk_drawing_area/graphics_gtk_drawing_area.c
@@ -49,6 +49,7 @@
 #include "plugin.h"
 #include "navit/font/freetype/font_freetype.h"
 #include "navit.h"
+#include <errno.h>
 
 #ifndef GDK_Book
 #define GDK_Book XF86XK_Book
@@ -428,6 +429,7 @@ draw_image(struct graphics_priv *gr, struct graphics_gc_priv *fg, struct point *
 	cairo_paint(gr->cairo);
 }
 
+#ifdef HAVE_IMLIB2
 static unsigned char*
 create_buffer_with_stride_if_required(unsigned char *input_buffer, int w, int h, size_t bytes_per_pixel, size_t output_stride)
 {
@@ -448,7 +450,6 @@ create_buffer_with_stride_if_required(unsigned char *input_buffer, int w, int h,
 	return out_buf;
 }
 
-#ifdef HAVE_IMLIB2
 static void
 draw_image_warp(struct graphics_priv *gr, struct graphics_gc_priv *fg, struct point *p, int count, struct graphics_image_priv *img)
 {
@@ -1037,7 +1038,11 @@ get_data(struct graphics_priv *this, char const *type)
 #if !defined(_WIN32) && !defined(__CEGCC__)
 		f=popen("pidof /usr/bin/ipaq-sleep","r");
 		if (f) {
-			fscanf(f,"%d",&this->pid);
+			int fscanf_result;
+			fscanf_result = fscanf(f,"%d",&this->pid);
+			if ((fscanf_result == EOF) || (fscanf_result == 0)){
+				dbg(lvl_warning, "Failed to open iPaq sleep file. Error-Code: %d\n" , errno);
+			}
 			dbg(lvl_debug,"ipaq_sleep pid=%d\n", this->pid);
 			pclose(f);
 		}
diff --git a/navit/graphics/opengl/graphics_opengl.c b/navit/graphics/opengl/graphics_opengl.c
index 98230f0dc..a0c2be2fe 100644
--- a/navit/graphics/opengl/graphics_opengl.c
+++ b/navit/graphics/opengl/graphics_opengl.c
@@ -50,7 +50,7 @@
 #define PIXEL_FORMAT GL_BGRA
 #endif
 
-#if HAVE_FREEIMAGE
+#ifdef HAVE_FREEIMAGE
 #include <FreeImage.h>
 #endif
 
@@ -371,7 +371,7 @@ static struct graphics_image_priv *
 image_new(struct graphics_priv *gr, struct graphics_image_methods *meth,
 	  char *path, int *w, int *h, struct point *hot, int rotation)
 {
-#if HAVE_FREEIMAGE
+#ifdef HAVE_FREEIMAGE
 	FIBITMAP *image;
 	RGBQUAD aPixel;
 	unsigned char *data;
@@ -527,7 +527,7 @@ image_new(struct graphics_priv *gr, struct graphics_image_methods *meth,
 		return gi;
 	}
 #else
-	dbg(lvl_error,"FreeImage not available - cannot load any images.\n", path);
+	dbg(lvl_error,"FreeImage not available - cannot load any images.\n");
 	return NULL;
 #endif
 }
diff --git a/navit/item.c b/navit/item.c
index 3f865c19d..2e00ea1fa 100644
--- a/navit/item.c
+++ b/navit/item.c
@@ -136,6 +136,9 @@ item_cleanup(void)
  * This function resets the "coordinate pointer" of an item to point to the first coordinate pair,
  * so that at the next call to {@code item_coord_get()} the first coordinates will be returned.
  *
+ * This function is not safe to call after destroying the item's map rect, and doing so may cause errors
+ * with some map implementations.
+ *
  * @param it The map item whose pointer is to be reset. This must be the active item, i.e. the last one retrieved from the
  * {@code map_rect}. There can only be one active item per {@code map_rect}.
  */
@@ -154,6 +157,9 @@ item_coord_rewind(struct item *it)
  * Coordinates are stored in the projection of the item's map. If you need them in a different projection,
  * call {@code item_coord_get_pro()} instead.
  *
+ * This function is not safe to call after destroying the item's map rect, and doing so may cause errors
+ * with some map implementations.
+ *
  * @param it The map item whose coordinates to retrieve. This must be the active item, i.e. the last one retrieved from the
  * {@code map_rect}. There can only be one active item per {@code map_rect}.
  * @param c Points to a buffer that will receive the coordinates.
@@ -170,6 +176,31 @@ item_coord_get(struct item *it, struct coord *c, int count)
 	return it->meth->item_coord_get(it->priv_data, c, count);
 }
 
+/**
+ * @brief Sets coordinates of an item
+ *
+ * This function supports different modes:
+ *
+ * \li `change_mode_delete`: Deletes the specified number of coordinates
+ * \li `change_mode_modify`: Replaces existing coordinates with new ones
+ * \li `change_mode_append`: Appends new coordinates
+ * \li `change_mode_prepend`: Prepends new coordinates
+ *
+ * TODO which coordinates are deleted/modified? Starting from the last coordinate retrieved, or the one after, or...?
+ *
+ * TODO what if `count` in delete or modify mode is bigger then the number of coordinates left?
+ *
+ * TODO where are coordinates appended/prepended? Beginning/end or current position?
+ *
+ * This function is not safe to call after destroying the item's map rect, and doing so may cause errors
+ * with some map implementations.
+ *
+ * @param it The map item whose coordinates to retrieve. This must be the active item, i.e. the last one retrieved from the
+ * {@code map_rect}. There can only be one active item per {@code map_rect}.
+ * @param c TODO new coordinates, also store for old coordinates (delete/modify)? Required in delete mode?
+ * @param count TODO number of coordinates to add, delete or modify?
+ * @param mode The change mode, see description
+ */
 int
 item_coord_set(struct item *it, struct coord *c, int count, enum change_mode mode)
 {
@@ -238,6 +269,18 @@ item_coord_get_pro(struct item *it, struct coord *c, int count, enum projection
 	return ret;
 }
 
+/**
+ * @brief Whether the current coordinates of an item correspond to a node.
+ *
+ * TODO which coordinates? Last retrieved or next (to be) retrieved?
+ *
+ * This function is not safe to call after destroying the item's map rect, and doing so may cause errors
+ * with some map implementations.
+ *
+ * @param it The item
+ *
+ * @return True on success, false on failure
+ */
 int 
 item_coord_is_node(struct item *it)
 {
@@ -246,18 +289,68 @@ item_coord_is_node(struct item *it)
 	return 0;
 }
 
+/**
+ * @brief Resets the "attribute pointer" of an item
+ *
+ * This function resets the "attribute pointer" of an item to point to the first attribute,
+ * so that at the next call to {@code item_attr_get()} the first attribute will be returned.
+ *
+ * This function is not safe to call after destroying the item's map rect, and doing so may cause errors
+ * with some map implementations.
+ *
+ * @param it The map item whose pointer is to be reset. This must be the active item, i.e. the last one retrieved from the
+ * {@code map_rect}. There can only be one active item per {@code map_rect}.
+ */
 void
 item_attr_rewind(struct item *it)
 {
 	it->meth->item_attr_rewind(it->priv_data);
 }
 
+/**
+ * @brief Gets the next matching attribute from an item
+ *
+ * This function returns the next attribute matching `attr_type` from an item and advances the
+ * "attribute pointer" accordingly, so that at the next call the next attribute will be returned.
+ *
+ * This function is not safe to call after destroying the item's map rect, and doing so may cause errors
+ * with some map implementations.
+ *
+ * @param it The map item whose attribute to retrieve. This must be the active item, i.e. the last one retrieved from the
+ * {@code map_rect}. There can only be one active item per {@code map_rect}.
+ * @param attr_type The attribute type to retrieve, or `attr_any` to retrieve the next attribute
+ * @param attr Receives the attribute retrieved
+ *
+ * @return True on success, false on failure
+ */
 int
 item_attr_get(struct item *it, enum attr_type attr_type, struct attr *attr)
 {
 	return it->meth->item_attr_get(it->priv_data, attr_type, attr);
 }
 
+/**
+ * @brief Sets an attribute of an item
+ *
+ * This function supports different modes:
+ *
+ * \li `change_mode_delete`: Deletes the attribute
+ * \li `change_mode_modify`: Replaces an attribute
+ * \li `change_mode_append`: Appends an attribute
+ * \li `change_mode_prepend`: Prepends an attribute
+ *
+ * TODO which attribute is deleted/modified? The last one retrieved, the next one, the first matching one?
+ *
+ * TODO where are attributes appended/prepended? Beginning/end or current position?
+ *
+ * This function is not safe to call after destroying the item's map rect, and doing so may cause errors
+ * with some map implementations.
+ *
+ * @param it The map item whose coordinates to retrieve. This must be the active item, i.e. the last one retrieved from the
+ * {@code map_rect}. There can only be one active item per {@code map_rect}.
+ * @param attr TODO new attr, also store for old attr (delete/modify)? Required in delete mode (type of attr to delete)?
+ * @param mode The change mode, see description
+ */
 int
 item_attr_set(struct item *it, struct attr *attr, enum change_mode mode)
 {
@@ -265,12 +358,14 @@ item_attr_set(struct item *it, struct attr *attr, enum change_mode mode)
 		return 0;
 	return it->meth->item_attr_set(it->priv_data, attr, mode);
 }
+
 /**
- * @brief Set map item type. 
+ * @brief Sets the type of a map item.
  *
- * @param it reference to the item.
- * @param type New type for the item. Setting it to type_none is expected to delete item from the map.
- * @return  Non-zero if this action is supported by the map and type is set successfully, 0 on error.
+ * @param it The item
+ * @param type The new type for the item. Setting it to type_none is expected to delete item from the map.
+ *
+ * @return Non-zero if this action is supported by the map and type is set successfully, 0 on error.
  */
 int
 item_type_set(struct item *it, enum item_type type)
diff --git a/navit/map.h b/navit/map.h
index 4ffe0d401..64261abc1 100644
--- a/navit/map.h
+++ b/navit/map.h
@@ -65,12 +65,16 @@ struct map_selection {
 };
 
 /**
- * @brief Holds all functions a map plugin has to implement to be useable
+ * @brief Holds all functions a map plugin has to implement to be usable
  *
- * This structure holds pointers to a map plugin's functions navit's core will call
- * to communicate with the plugin. For further information look into map.c - there exist
+ * This structure holds pointers to a map plugin's functions, which Navit's core will call
+ * to communicate with the plugin. For further information look into map.c, which has
  * functions with the same names acting more or less as "wrappers" around the functions here.
  * Especially the arguments (and their meaning) of each function will be described there.
+ *
+ * Note that there is no separate method to remove an item from a map. This is instead accomplished by
+ * retrieving the item, then setting its type to `type_none` via its `item_type_set` method (provided
+ * the item and its map support removal).
  */
 struct map_methods {
 	enum projection pro;        /**< The projection used for that type of map */