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>
2017-07-28 10:48:48 -03:00
parent 14bf91af44
commit e0a1862ce3
51 changed files with 486 additions and 434 deletions
--- a/api/mraa/aio.hpp
+++ b/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)
    {
--- a/api/mraa/common.h
+++ b/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
--- a/api/mraa/common.hpp
+++ b/api/mraa/common.hpp
@@ -99,7 +99,7 @@ getPlatformType()
 /**
 * Print a textual representation of the mraa::Result
 *
- * @param Result the Result to print
+ * @param result the Result to print
 */
 inline void
 printError(Result result)
@@ -157,7 +157,7 @@ getPlatformName()
 /**
 * Return platform versioning info. Returns NULL if no info present.
 *
- * @param optional subplatform identifier
+ * @param platform_offset optional subplatform identifier
 * @return platform versioning info
 */
 inline std::string
@@ -315,7 +315,7 @@ getPwmLookup(std::string pwm_name)
 /**
 * Get UART index by UART name, board must be initialised.
 *
- * @param pwm_name: Name of the UART. Eg: UART2
+ * @param uart_name: Name of the UART. Eg: UART2
 * @throws std::invalid_argument if name is not found
 * @return MRAA index for the UART
 */
@@ -360,7 +360,7 @@ hasSubPlatform()
 /**
 * 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
 */
@@ -373,7 +373,7 @@ isSubPlatformId(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
 */
@@ -386,7 +386,7 @@ getSubPlatformId(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
 */
@@ -399,7 +399,7 @@ getSubPlatformIndex(int pin_or_bus_id)
 /**
 * Get default i2c bus, board must be initialised.
 *
- * @param optional subplatform identifier
+ * @param platform_offset optional subplatform identifier
 * @return default i2c bus for paltform
 */
 inline int
@@ -422,6 +422,13 @@ addSubplatform(Platform subplatformtype, std::string uart_dev)
    return (Result) mraa_add_subplatform((mraa_platform_t) subplatformtype, uart_dev.c_str());
 }

+/**
+ * Remove mraa subplatform
+ *
+ * @param subplatformtype the type of subplatform to remove
+ * (e.g. MRAA_GENERIC_FIRMATA)
+ * @return Result of operation
+ */
 inline Result
 removeSubplatform(Platform subplatformtype)
 {
@@ -435,7 +442,7 @@ removeSubplatform(Platform subplatformtype)
 * [io]-[raw]-[id]-[pin]
 * [io]-[raw]-[path]
 *
- * @param IO description
+ * @param desc description
 *
 * @return class T initialised using pointer to IO or NULL
 */
@@ -449,7 +456,7 @@ initIo(std::string 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 Result indicating success
--- a/api/mraa/firmata.h
+++ b/api/mraa/firmata.h
@@ -52,7 +52,7 @@ typedef struct _firmata* mraa_firmata_context;
 * Initialise firmata context on a feature. This feature is what will be
 * listened on if you request a response callback
 *
- * @param firmata feature
+ * @param feature firmata feature
 * @return firmata context or NULL
 */
 mraa_firmata_context mraa_firmata_init(int feature);
--- a/api/mraa/gpio.h
+++ b/api/mraa/gpio.h
@@ -242,7 +242,7 @@ int mraa_gpio_get_pin_raw(mraa_gpio_context dev);
 * @param mode Mode to set input pin state
 * @return Result of operation
 */
-mraa_result_t mraa_gpio_input_mode(mraa_gpio_context dev, mraa_gpio_input_mode_t);
+mraa_result_t mraa_gpio_input_mode(mraa_gpio_context dev, mraa_gpio_input_mode_t mode);

 /**
 * Set Gpio output driver mode. This is not a standard feature, it needs custom implementation for each board
--- a/api/mraa/gpio.hpp
+++ b/api/mraa/gpio.hpp
@@ -127,7 +127,7 @@ class Gpio
     * Gpio Constructor, takes a pointer to the GPIO context and initialises
     * the GPIO class
     *
-     * @param void * to GPIO context
+     * @param gpio_context void * to GPIO context
     */
    Gpio(void* gpio_context)
    {
--- a/api/mraa/i2c.hpp
+++ b/api/mraa/i2c.hpp
@@ -65,7 +65,7 @@ class I2c
    /**
     * I2C constructor, takes a pointer to a I2C context and initialises the I2C class
     *
-     * @param void * to an I2C context
+     * @param i2c_context void * to an I2C context
     */
    I2c(void* i2c_context)
    {
--- a/api/mraa/iio.h
+++ b/api/mraa/iio.h
@@ -27,22 +27,37 @@
 #include "common.h"
 #include "iio_kernel_headers.h"

+/** Mraa Iio Channels */
 typedef struct {
+    /** Channel index */
    int index;
+    /** Channel enabled/disabled */
    int enabled;
+    /** Channel type */
    char* type;
+    /** Channel endianes */
    mraa_boolean_t lendian;
+    /** Channel signed */
    int signedd;
+    /** Channel offset */
    unsigned int offset;
+    /** Channel mask */
    uint64_t mask;
+    /** Channel used bits */
    unsigned int bits_used;
+    /** Channel bytes */
    unsigned int bytes;
+    /** Channel shift */
    unsigned int shift;
+    /** Channel location */
    unsigned int location;
 } mraa_iio_channel;

+/** Mraa Iio Event */
 typedef struct {
+    /** Event name */
    char* name;
+    /** Event enabled/disabled */
    int enabled;
 } mraa_iio_event;

@@ -74,44 +89,171 @@ typedef struct _iio* mraa_iio_context;
 /**
 * Initialise iio context
 *
- * @param bus iio device to use
+ * @param device iio device to use
 * @return i2c context or NULL
 */
 mraa_iio_context mraa_iio_init(int device);

+/**
+ * Trigger buffer
+ *
+ * @param dev The iio context
+ * @param fptr Callback
+ * @param args Arguments
+ * @return Result of operation
+ */
 mraa_result_t mraa_iio_trigger_buffer(mraa_iio_context dev, void (*fptr)(char* data), void* args);

+/**
+ * Get device name
+ *
+ * @param dev The iio context
+ * @return Name of the device
+ */
 const char* mraa_iio_get_device_name(mraa_iio_context dev);

+/**
+ * Get device number
+ *
+ * @param name Name of the device
+ * @return Device Number
+ */
 int mraa_iio_get_device_num_by_name(const char* name);

+/**
+ * Read size
+ *
+ * @param dev The iio context
+ * @return Size
+ */
 int mraa_iio_read_size(mraa_iio_context dev);

+/**
+ * Get channels
+ *
+ * @param dev The iio context
+ * @return Channels
+ */
 mraa_iio_channel* mraa_iio_get_channels(mraa_iio_context dev);

+/**
+ * Get channels count
+ *
+ * @param dev The iio context
+ * @return Channels count
+ */
 int mraa_iio_get_channel_count(mraa_iio_context dev);

+/**
+ * Read float from file
+ *
+ * @param dev The iio context
+ * @param filename Filename
+ * @param data Data
+ * @return Result of operation
+ */
 mraa_result_t mraa_iio_read_float(mraa_iio_context dev, const char* filename, float* data);

+/**
+ * Read int from file
+ *
+ * @param dev The iio context
+ * @param filename Filename
+ * @param data Data
+ * @return Result of operation
+ */
 mraa_result_t mraa_iio_read_int(mraa_iio_context dev, const char* filename, int* data);

+/**
+ * Read String from file
+ *
+ * @param dev The iio context
+ * @param filename Filename
+ * @param data Data
+ * @param max_len Max lenght to read
+ * @return Result of operation
+ */
 mraa_result_t mraa_iio_read_string(mraa_iio_context dev, const char* filename, char* data, int max_len);

+/**
+ * Write float
+ *
+ * @param dev The iio context
+ * @param attr_chan Channel attributes
+ * @param data Float to write
+ * @return Result of operation
+ */
 mraa_result_t mraa_iio_write_float(mraa_iio_context dev, const char* attr_chan, const float data);

+/**
+ * Write int
+ *
+ * @param dev The iio context
+ * @param attr_chan Channel attributes
+ * @param data Int to write
+ * @return Result of operation
+ */
 mraa_result_t mraa_iio_write_int(mraa_iio_context dev, const char* attr_chan, const int data);

+/**
+ * Write string
+ *
+ * @param dev The iio context
+ * @param attr_chan Channel attributes
+ * @param data String to write
+ * @return Result of operation
+ */
 mraa_result_t mraa_iio_write_string(mraa_iio_context dev, const char* attr_chan, const char* data);

+/**
+ * Get channel data
+ *
+ * @param dev The iio context
+ * @return Result of operation
+ */
 mraa_result_t mraa_iio_get_channel_data(mraa_iio_context dev);

+/**
+ * Get event data
+ *
+ * @param dev The iio context
+ * @return Result of operation
+ */
 mraa_result_t mraa_iio_get_event_data(mraa_iio_context dev);

+/**
+ * Event poll
+ *
+ * @param dev The iio context
+ * @param data Data
+ * @return Result of operation
+ */
 mraa_result_t mraa_iio_event_poll(mraa_iio_context dev, struct iio_event_data* data);

+/**
+ * Setup event callback
+ *
+ * @param dev The iio context
+ * @param fptr Callback
+ * @param args Arguments
+ * @return Result of operation
+ */
 mraa_result_t
 mraa_iio_event_setup_callback(mraa_iio_context dev, void (*fptr)(struct iio_event_data* data, void* args), void* args);

+/**
+ * Extract event
+ *
+ * @param event Event
+ * @param chan_type Channel type
+ * @param modifier Modifier
+ * @param type Type
+ * @param direction Direction
+ * @param channel Channel
+ * @param channel2 Channel2
+ * @param different Different
+ * @return Result of operation
+ */
 mraa_result_t mraa_iio_event_extract_event(struct iio_event_data* event,
                                           int* chan_type,
                                           int* modifier,
@@ -121,11 +263,32 @@ mraa_result_t mraa_iio_event_extract_event(struct iio_event_data* event,
                                           int* channel2,
                                           int* different);

+/**
+ * Get mount matrix
+ * @param dev The iio context
+ * @param sysfs_name Sysfs name
+ * @param mm Matrix
+ * @return Result of operation
+ */
 mraa_result_t mraa_iio_get_mount_matrix(mraa_iio_context dev, const char *sysfs_name, float mm[9]);

+/**
+ * Create trigger
+ *
+ * @param dev The iio context
+ * @param trigger Trigger name
+ * @return Result of operation
+ */
 mraa_result_t mraa_iio_create_trigger(mraa_iio_context dev, const char* trigger);

+/**
+ * Update channels
+ *
+ * @param dev The iio context
+ * @return Result of operation
+ */
 mraa_result_t mraa_iio_update_channels(mraa_iio_context dev);
+
 /**
 * De-inits an mraa_iio_context device
 *
--- a/api/mraa/iio.hpp
+++ b/api/mraa/iio.hpp
@@ -25,28 +25,39 @@
 #pragma once

 #include <stdexcept>
- #include <sstream>
+#include <sstream>
 #include "iio.h"
 #include "types.hpp"

 namespace mraa
 {

+/** Iio Event Data */
 struct IioEventData
 {
+    /** Channel Type */
    int channelType;
+    /** Modifier */
    int modifier;
+    /** Type */
    int type;
+    /** Direction */
    int direction;
+    /** Channel */
    int channel;
+    /** Channel 2 */
    int channel2;
+    /** Difference */
    int diff;
 };

+/** Iio Handler */
 class IioHandler
 {
 public:
+  /** onIioEvent Handler */
  virtual void onIioEvent(const IioEventData& eventData) = 0;
+  /** Destructor */
  virtual ~IioHandler() {};     // add an empty destructor to get rid of warning
 };

@@ -56,7 +67,7 @@ public:
 *
 * This file defines the C++ iio interface for libmraa
 *
- * @snippet iio_dummy_test.cpp Interesting
+ * @snippet Iio-dummy.cpp Interesting
 */
 class Iio
 {
--- a/api/mraa/iio_kernel_headers.h
+++ b/api/mraa/iio_kernel_headers.h
@@ -115,12 +115,11 @@ enum iio_event_direction {

 /**
 * struct iio_event_data - The actual event being pushed to userspace
- * @id:		event identifier
- * @timestamp:	best estimate of time of event occurrence (often from
- *		the interrupt handler)
 */
 struct iio_event_data {
+  /** event identifier */
 	unsigned long long int	id;
+  /** best estimate of time of event occurrence (often from the interrupt handler) */
 	long long int	timestamp;
 };

--- a/api/mraa/pwm.h
+++ b/api/mraa/pwm.h
@@ -45,6 +45,7 @@ extern "C" {

 #include "common.h"

+/** Mraa Pwm Context */
 typedef struct _pwm* mraa_pwm_context;

 /**
--- a/api/mraa/pwm.hpp
+++ b/api/mraa/pwm.hpp
@@ -71,7 +71,7 @@ class Pwm
     * Pwm constructor, takes a pointer to the PWM context and
     * initialises the class
     *
-     * @param void * to a PWM context
+     * @param pwm_context void * to a PWM context
     */
    Pwm(void* pwm_context)
    {
--- a/api/mraa/spi.hpp
+++ b/api/mraa/spi.hpp
@@ -71,7 +71,7 @@ class Spi
    }

    /**
-     * Initialise SPI object using 'raw' mode. Mraa will go and grab the spidev device lablled /dev/spidev<bus>.<cs>
+     * Initialise SPI object using 'raw' mode. Mraa will go and grab the spidev device lablled /dev/spidev[bus].[cs]
     *
     * @param bus to use
     * @param cs to use
@@ -89,7 +89,7 @@ class Spi
     * Spi Constructor, takes a pointer to a SPI context and initialises
     * the SPI class
     *
-     * @param void * to SPI context
+     * @param spi_context void * to SPI context
     */
    Spi(void* spi_context)
    {
--- a/api/mraa/types.h
+++ b/api/mraa/types.h
@@ -245,6 +245,9 @@ typedef enum {
    MRAA_I2C_HIGH = 2  /**< up to 3.4Mhz */
 } mraa_i2c_mode_t;

+/**
+ * Enum representing different uart parity states
+ */
 typedef enum {
    MRAA_UART_PARITY_NONE = 0,
    MRAA_UART_PARITY_EVEN = 1,
--- a/api/mraa/types.hpp
+++ b/api/mraa/types.hpp
@@ -231,7 +231,7 @@ typedef enum {
 } Pinmodes;

 /**
- * Enum reprensenting different i2c speeds/modes
+ * Enum representing different i2c speeds/modes
 */
 typedef enum {
    I2C_STD = 0,  /**< up to 100Khz */
@@ -239,6 +239,9 @@ typedef enum {
    I2C_HIGH = 2  /**< up to 3.4Mhz */
 } I2cMode;

+/**
+ * Enum representing different uart parity states
+ */
 typedef enum {
    UART_PARITY_NONE = 0,
    UART_PARITY_EVEN = 1,
--- a/api/mraa/uart.h
+++ b/api/mraa/uart.h
@@ -45,6 +45,7 @@ extern "C" {

 #include "common.h"

+/** Mraa Uart Context */
 typedef struct _uart* mraa_uart_context;

 /**
--- a/api/mraa/uart.hpp
+++ b/api/mraa/uart.hpp
@@ -64,7 +64,7 @@ class Uart
     * Uart Constructor, takes a string to the path of the serial
     * interface that is needed.
     *
-     * @param uart the index of the uart set to use
+     * @param path the index of the uart set to use
     */
    Uart(std::string path)
    {
@@ -79,7 +79,7 @@ class Uart
     * Uart Constructor, takes a pointer to the UART context and initialises
     * the UART class
     *
-     * @param void * to a UART context
+     * @param uart_context void * to a UART context
     */
    Uart(void* uart_context)
    {
@@ -160,7 +160,7 @@ class Uart
    /**
     * Write bytes in String object to a device
     *
-     * @param string to write
+     * @param data string to write
     * @return the number of bytes written, or -1 if an error occurred
     */
    int
@@ -273,7 +273,6 @@ class Uart
    /**
     * Set the blocking state for write operations
     *
-     * @param dev The UART context
     * @param nonblock new nonblocking state
     * @return Result of operation
     */
--- a/api/mraa/uart_ow.h
+++ b/api/mraa/uart_ow.h
@@ -64,16 +64,20 @@ extern "C" {
 #include "common.h"
 #include "uart.h"

-/* 8 bytes (64 bits) for a device rom code */
+/** 8 bytes (64 bits) for a device rom code */
 #define MRAA_UART_OW_ROMCODE_SIZE 8

-/* for now, we simply use the normal MRAA UART context */
+/** for now, we simply use the normal MRAA UART context */
 typedef struct _mraa_uart_ow {
+    /** Uart Context */
    mraa_uart_context uart;
-    /* search state */
+    /** search state */
    unsigned char ROM_NO[MRAA_UART_OW_ROMCODE_SIZE]; /* 8 byte (64b) rom code */
+    /** Context laxt discrepancy  */
    int LastDiscrepancy;
+    /** Context las family discrepancy */
    int LastFamilyDiscrepancy;
+    /** Context las device flag */
    mraa_boolean_t LastDeviceFlag;
 } *mraa_uart_ow_context;

--- a/api/mraa/uart_ow.hpp
+++ b/api/mraa/uart_ow.hpp
@@ -46,8 +46,8 @@ class UartOW
     * UartOW Constructor, takes a pin number which will map directly to the
     * linux uart number, this 'enables' the uart, nothing more
     *
-     * @throws std::invalid_argument in case of error
     * @param uart the index of the uart to use
+     * @throws std::invalid_argument in case of error
     */
    UartOW(int uart)
    {
@@ -62,8 +62,8 @@ class UartOW
     * UartOW Constructor, takes a string to the path of the serial
     * interface that is needed.
     *
-     * @throws std::invalid_argument in case of error
     * @param path the file path for the UART to use
+     * @throws std::invalid_argument in case of error
     */
    UartOW(std::string path)
    {