Travis CI and Documentation Generation improvements

* Use docker images from docker hub instead of building them on Travis
* Fix doxygen warnings for C/C++ Documentation
* Fix examples inclusion in documentation
* Modify Travis build matrix to include stages and additional jobs
* Update doxygen2jsdoc submodule
* Add doxyport submodule
* Generate documentation for each language in Travis
* Add sonar.java.binaries to sonar-scan.sh

Signed-off-by: Nicolas Oliver <dario.n.oliver@intel.com>

.gitmodules

@@ -1,4 +1,8 @@
 [submodule "doxygen2jsdoc"]
 	path = doxygen2jsdoc
-	url = https://github.com/arfoll/doxygen2jsdoc.git
+	url = https://github.com/intel-iot-devkit/doxygen2jsdoc.git
+	branch = master
+[submodule "doxyport"]
+	path = doxyport
+	url = https://github.com/intel-iot-devkit/doxyport.git
 	branch = master

.travis.yml

@@ -3,54 +3,6 @@ sudo: required
 
 language: cpp
 
-compiler:
-  - clang
-  - gcc
-
-env:
-  - TARGET=doc
-  - TARGET=python2
-  - TARGET=python3
-  - TARGET=java
-  - TARGET=node4
-  - TARGET=node5
-  - TARGET=android
-  - TARGET=sonar-scan
-  - JSONPLAT=ON TARGET=python2
-  - JSONPLAT=ON TARGET=python3
-  - JSONPLAT=ON TARGET=java
-  - JSONPLAT=ON TARGET=node4
-  - JSONPLAT=ON TARGET=node5
-  - BUILDARCH=MOCK TARGET=python2
-  - BUILDARCH=MOCK TARGET=python3
-  - BUILDARCH=MOCK TARGET=java
-  - BUILDARCH=MOCK TARGET=node4
-  - BUILDARCH=MOCK TARGET=node5
-
-matrix:
-  exclude:
-    - compiler: clang
-      env: TARGET=java
-    - compiler: clang
-      env: JSONPLAT=ON TARGET=java
-    - compiler: clang
-      env: BUILDARCH=MOCK TARGET=java
-    - compiler: gcc
-      env: TARGET=android
-    - compiler: clang
-      env: TARGET=sonar-scan
-  allow_failures:
-    - compiler: gcc
-      env: JSONPLAT=ON TARGET=node4
-    - compiler: clang
-      env: JSONPLAT=ON TARGET=node4
-    - compiler: gcc
-      env: JSONPLAT=ON TARGET=node5
-    - compiler: clang
-      env: JSONPLAT=ON TARGET=node5
-    - compiler: gcc
-      env: TARGET=sonar-scan
-
 services:
   - docker
 
@@ -60,14 +12,90 @@ before_install:
   - chmod +x docker-compose
   - sudo mv docker-compose /usr/local/bin
 
-before_script:
-  - if [ "$CC" == "gcc" ]; then export CC=gcc-4.8; fi
-  - if [ "$CXX" == "g++" ]; then export CXX=g++-4.8; fi
-  - if [ "$CC" == "clang" ]; then export CC=clang-3.8; fi
-  - if [ "$CXX" == "clang++" ]; then export CXX=clang++-3.8; fi
-  - docker-compose build base
-  - if [ "$TARGET" == "android" ]; then docker-compose build java; fi
-  - docker-compose build ${TARGET}
-
-script:
-  - docker-compose run ${TARGET}
+jobs:
+  fast_finish: true
+  allow_failures:
+    - env: TARGET=sonar-scan
+    - env: TARGET=ipk
+    - env: TARGET=rpm
+  include:
+    - &run-with-clang
+      stage: Clang 3.8
+      env: TARGET=python2
+      before_script: docker-compose pull ${TARGET}
+      script:
+        - export CC=clang-3.8 CXX=clang++-3.8
+        - docker-compose run ${TARGET}
+        - BUILDARCH=MOCK docker-compose run ${TARGET}
+        - if [[ ${TARGET} != *"node"* ]]; then JSONPLAT=ON docker-compose run ${TARGET}; fi
+    - <<: *run-with-clang
+      env: TARGET=python3
+    - <<: *run-with-clang
+      env: TARGET=node4
+    - <<: *run-with-clang
+      env: TARGET=node5
+    - <<: *run-with-clang
+      env: TARGET=node6
+    - <<: *run-with-clang
+      env: TARGET=java
+    - &run-with-gcc-5
+      stage: Gcc 5
+      env: TARGET=python2
+      before_script: docker-compose pull ${TARGET}
+      script:
+        - export CC=gcc-5 CXX=g++-5
+        - docker-compose run ${TARGET}
+        - BUILDARCH=MOCK docker-compose run ${TARGET}
+        - if [[ ${TARGET} != *"node"* ]]; then JSONPLAT=ON docker-compose run ${TARGET}; fi
+    - <<: *run-with-gcc-5
+      env: TARGET=python3
+    - <<: *run-with-gcc-5
+      env: TARGET=node4
+    - <<: *run-with-gcc-5
+      env: TARGET=node5
+    - <<: *run-with-gcc-5
+      env: TARGET=node6
+    - <<: *run-with-gcc-5
+      env: TARGET=java
+    - &run-with-gcc-6
+      stage: Gcc 6
+      env: TARGET=python2
+      before_script: docker-compose pull ${TARGET}
+      script:
+        - export CC=gcc-6 CXX=g++-6
+        - docker-compose run ${TARGET}
+        - BUILDARCH=MOCK docker-compose run ${TARGET}
+        - if [[ ${TARGET} != *"node"* ]]; then JSONPLAT=ON docker-compose run ${TARGET}; fi
+    - <<: *run-with-gcc-6
+      env: TARGET=python3
+    - <<: *run-with-gcc-6
+      env: TARGET=node4
+    - <<: *run-with-gcc-6
+      env: TARGET=node5
+    - <<: *run-with-gcc-6
+      env: TARGET=node6
+    - <<: *run-with-gcc-6
+      env: TARGET=java
+    - &run-additional-jobs
+      stage: Additional Jobs
+      env: TARGET=doc
+      before_script: docker-compose pull ${TARGET}
+      script:
+        - export CC=clang-3.8 CXX=clang++-3.8
+        - docker-compose run ${TARGET}
+    - <<: *run-additional-jobs
+      env: TARGET=android
+    - <<: *run-additional-jobs
+      env: TARGET=usbplat
+    - <<: *run-additional-jobs
+      env: TARGET=firmata
+    - <<: *run-additional-jobs
+      env: TARGET=imraa
+    - <<: *run-additional-jobs
+      env: TARGET=ftdi4442
+    - <<: *run-additional-jobs
+      env: TARGET=ipk
+    - <<: *run-additional-jobs
+      env: TARGET=rpm
+    - <<: *run-additional-jobs
+      env: TARGET=sonar-scan

Doxyfile.in

@@ -832,7 +832,7 @@ RECURSIVE              = NO
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = 
+EXCLUDE                = @CMAKE_CURRENT_SOURCE_DIR@/docs/index.java.md
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded

Doxyfile.java.in

@@ -756,10 +756,9 @@ WARN_LOGFILE           =
 INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/api/ \
                          @CMAKE_CURRENT_SOURCE_DIR@/api/mraa/ \
                          @CMAKE_CURRENT_SOURCE_DIR@/docs/ \
-                         @CMAKE_CURRENT_SOURCE_DIR@/docs/CONTRIBUTING.md \
+                         @CMAKE_CURRENT_SOURCE_DIR@/CONTRIBUTING.md \
                          @CMAKE_BINARY_DIR@/src/ \
-                         @CMAKE_CURRENT_SOURCE_DIR@/docs/index.java.md \
-                         @CMAKE_CURRENT_SOURCE_DIR@/README.md
+                         @CMAKE_CURRENT_SOURCE_DIR@/docs/index.java.md
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -797,7 +796,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = @CMAKE_CURRENT_SOURCE_DIR@/docs/index.md
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -1810,18 +1809,6 @@ GENERATE_XML           = YES
 
 XML_OUTPUT             = xml
 
-# The XML_SCHEMA tag can be used to specify a XML schema, which can be used by a
-# validating XML parser to check the syntax of the XML files.
-# This tag requires that the tag GENERATE_XML is set to YES.
-
-XML_SCHEMA             =
-
-# The XML_DTD tag can be used to specify a XML DTD, which can be used by a
-# validating XML parser to check the syntax of the XML files.
-# This tag requires that the tag GENERATE_XML is set to YES.
-
-XML_DTD                =
-
 # If the XML_PROGRAMLISTING tag is set to YES doxygen will dump the program
 # listings (including syntax highlighting and cross-referencing information) to
 # the XML output. Note that enabling this will significantly increase the size

api/mraa/aio.hpp

@@ -60,7 +60,7 @@ class Aio
      * position. Check your board mapping for details. An arduino style layout
      * will have A0 as pin14 but AIO0.
      *
-     * @param void * to an AIO context
+     * @param aio_context void * to an AIO context
      */
     Aio(void* aio_context)
     {

api/mraa/common.h

@@ -27,13 +27,19 @@
 #include <stdint.h>
 #include "types.h"
 
+/** Max size off Mraa Platform name */
 #define MRAA_PLATFORM_NAME_MAX_SIZE 64
+/** Size off Mraa pin name */
 #define MRAA_PIN_NAME_SIZE 12
 
+/** Bit Shift for Mraa sub platform */
 #define MRAA_SUB_PLATFORM_BIT_SHIFT 9
+/** Mask for Mraa sub platform */
 #define MRAA_SUB_PLATFORM_MASK (1<<MRAA_SUB_PLATFORM_BIT_SHIFT)
 
+/** Mraa main platform offset */
 #define MRAA_MAIN_PLATFORM_OFFSET 0
+/** Mraa sub platform offset */
 #define MRAA_SUB_PLATFORM_OFFSET 1
 
 /** Executes function func and returns its result in case of error
@@ -106,7 +112,7 @@ unsigned int mraa_adc_raw_bits();
 /**
  * Check the specified board's bit size when reading the value
  *
- * @param specified platform offset; 0 for main platform, 1 foor sub platform
+ * @param platform_offset specified platform offset; 0 for main platform, 1 for sub platform
  * @return raw bits being read from kernel module. zero if no ADC
  */
 unsigned int mraa_get_platform_adc_raw_bits(uint8_t platform_offset);
@@ -121,7 +127,7 @@ unsigned int mraa_adc_supported_bits();
 /**
  * Return value that the raw value should be shifted to. Zero if no ADC
  *
- * @param specified platform offset; 0 for main platform, 1 foor sub platform
+ * @param platform_offset specified platform offset; 0 for main platform, 1 for sub platform
  * @return return actual bit size the adc value should be understood as.
  */
 unsigned int mraa_get_platform_adc_supported_bits(int platform_offset);
@@ -146,7 +152,7 @@ const char* mraa_get_platform_name();
  * platform and can be NULL. platform_offset has to be given. Do not modify
  * this pointer
  *
- * @param specified platform offset; 0 for main platform, 1 for sub platform
+ * @param platform_offset specified platform offset; 0 for main platform, 1 for sub platform
  * @return platform's versioning string
  */
 const char* mraa_get_platform_version(int platform_offset);
@@ -255,7 +261,7 @@ int mraa_get_i2c_bus_id(int i2c_bus);
 /**
  * Get specified platform pincount, board must be initialised.
  *
- * @param specified platform offset; 0 for main platform, 1 foor sub platform
+ * @param platform_offset specified platform offset; 0 for main platform, 1 for sub platform
  * @return uint of physical pin count on the in-use platform
  */
 unsigned int mraa_get_platform_pin_count(uint8_t platform_offset);
@@ -326,7 +332,7 @@ mraa_boolean_t mraa_has_sub_platform();
 /**
  * Check if pin or bus id includes sub platform mask.
  *
- * @param int pin or bus number
+ * @param pin_or_bus_id pin or bus number
  *
  * @return mraa_boolean_t 1 if pin or bus is for sub platform, 0 otherwise
  */
@@ -335,7 +341,7 @@ mraa_boolean_t mraa_is_sub_platform_id(int pin_or_bus_id);
 /**
  * Convert pin or bus index to corresponding sub platform id.
  *
- * @param int pin or bus index
+ * @param pin_or_bus_index pin or bus index
  *
  * @return int sub platform pin or bus number
  */
@@ -344,7 +350,7 @@ int mraa_get_sub_platform_id(int pin_or_bus_index);
 /**
  * Convert pin or bus sub platform id to index.
  *
- * @param int sub platform pin or bus id
+ * @param pin_or_bus_id sub platform pin or bus id
  *
  * @return int pin or bus index
  */
@@ -353,8 +359,8 @@ int mraa_get_sub_platform_index(int pin_or_bus_id);
 /**
  * Add mraa subplatform
  *
- * @param subplatform type
- * @param uart device subplatform is on
+ * @param subplatformtype subplatform type
+ * @param uart_dev uart device subplatform is on
  *
  * @return mraa_result_t indicating success
  */
@@ -363,7 +369,7 @@ mraa_result_t mraa_add_subplatform(mraa_platform_t subplatformtype, const char*
 /**
  * Remove a mraa subplatform
  *
- * @param subplatform type
+ * @param subplatformtype subplatform type
  *
  * @return mraa_result indicating success
  */
@@ -376,7 +382,7 @@ mraa_result_t mraa_remove_subplatform(mraa_platform_t subplatformtype);
  * [io]-[raw]-[id]-[pin]
  * [io]-[raw]-[path]
  *
- * @param IO description
+ * @param desc IO description
  *
  * @return void* to IO context or NULL
  */
@@ -385,7 +391,7 @@ void* mraa_init_io(const char* desc);
 /**
  * Instantiate an unknown board using a json file
  *
- * @param Path to the json file, relative to the folder the program
+ * @param path Path to the json file, relative to the folder the program
  * was initially run in or a direct path
  *
  * @return mraa_result indicating success