diff --git a/Doxyfile.in b/Doxyfile.in
index a4c441e..da05e2e 100644
--- a/Doxyfile.in
+++ b/Doxyfile.in
@@ -99,7 +99,7 @@ BRIEF_MEMBER_DESC = YES
# brief descriptions will be completely suppressed.
# The default value is: YES.
-REPEAT_BRIEF = YES
+REPEAT_BRIEF = NO
# This tag implements a quasi-intelligent brief description abbreviator that is
# used to form the text in various listings. Each string in this list, if found
@@ -129,6 +129,8 @@ ABBREVIATE_BRIEF = "The $name class" \
ALWAYS_DETAILED_SEC = NO
+DETAILS_AT_TOP = YES
+
# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
# inherited members of a class in the documentation of that class as if those
# members were ordinary class members. Constructors, destructors and assignment
@@ -510,7 +512,7 @@ HIDE_SCOPE_NAMES = YES
# the files that are included by a file in the documentation of that file.
# The default value is: YES.
-SHOW_INCLUDE_FILES = YES
+SHOW_INCLUDE_FILES = NO
# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
# grouped member an include statement to the documentation, telling the reader
@@ -536,7 +538,7 @@ INLINE_INFO = YES
# name. If set to NO the members will appear in declaration order.
# The default value is: YES.
-SORT_MEMBER_DOCS = YES
+SORT_MEMBER_DOCS = NO
# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
# descriptions of file, namespace and class members alphabetically by member
@@ -671,7 +673,7 @@ FILE_VERSION_FILTER =
# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
# tag is left empty.
-LAYOUT_FILE =
+LAYOUT_FILE = @CMAKE_CURRENT_SOURCE_DIR@/DoxygenLayout.xml
# The CITE_BIB_FILES tag can be used to specify one or more bib files containing
# the reference definitions. This must be a list of .bib files. The .bib
@@ -753,7 +755,10 @@ WARN_LOGFILE =
# spaces.
# Note: If this tag is empty the current directory is searched.
-INPUT = @CMAKE_CURRENT_SOURCE_DIR@/api/ @CMAKE_CURRENT_SOURCE_DIR@/README.md
+INPUT = @CMAKE_CURRENT_SOURCE_DIR@/api/ \
+ @CMAKE_CURRENT_SOURCE_DIR@/README.md \
+ @CMAKE_CURRENT_SOURCE_DIR@/include/ \
+ @CMAKE_CURRENT_SOURCE_DIR@/docs/
# 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
@@ -863,7 +868,8 @@ EXCLUDE_SYMBOLS =
# command).
EXAMPLE_PATH = @CMAKE_CURRENT_SOURCE_DIR@/examples/ \
- @CMAKE_CURRENT_SOURCE_DIR@/examples/c++/
+ @CMAKE_CURRENT_SOURCE_DIR@/examples/c++/ \
+ @CMAKE_CURRENT_SOURCE_DIR@/docs/
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -2206,7 +2212,7 @@ INCLUDE_GRAPH = YES
# The default value is: YES.
# This tag requires that the tag HAVE_DOT is set to YES.
-INCLUDED_BY_GRAPH = YES
+INCLUDED_BY_GRAPH = NO
# If the CALL_GRAPH tag is set to YES then doxygen will generate a call
# dependency graph for every global function or class method.
diff --git a/DoxygenLayout.xml b/DoxygenLayout.xml
new file mode 100644
index 0000000..4af56fd
--- /dev/null
+++ b/DoxygenLayout.xml
@@ -0,0 +1,194 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/README.md b/README.md
index 0da1559..a906906 100644
--- a/README.md
+++ b/README.md
@@ -16,37 +16,24 @@ classes directly wrap the C API and provide a near 1:1 mapping of
functionality.
-C API Modules | C++ API Classes
-:-------------------:|:-------------------:
- @ref gpio.h "gpio" | @ref maa::Gpio "Gpio class"
- @ref i2c.h "i2c" | @ref maa::I2c "I2c class"
- @ref aio.h "aio" | @ref maa::Aio "Aio class"
- @ref pwm.h "pwm" | @ref maa::Pwm "Pwm class"
- @ref spi.h "spi" | @ref maa::Spi "Spi class"
- @ref maa.h "maa" | @ref maa.h "maa"
+| C API Modules | C++ API Classes |
+|:-------------------:|:---------------------------:|
+| @ref gpio.h "gpio" | @ref maa::Gpio "Gpio class" |
+| @ref i2c.h "i2c" | @ref maa::I2c "I2c class" |
+| @ref aio.h "aio" | @ref maa::Aio "Aio class" |
+| @ref pwm.h "pwm" | @ref maa::Pwm "Pwm class" |
+| @ref spi.h "spi" | @ref maa::Spi "Spi class" |
+| @ref maa.h "maa" | @ref maa.h "maa" |
### Hello Maa
@snippet hellomaa.c Interesting
-### Basic GPIO
-@snippet gpio_read6.c Interesting
-
-### Basic PWM
-@snippet cycle-pwm3.c Interesting
-
-### Basic I2C
-@snippet analogin_a0.c Interesting
-
-### Basic AIO
-@snippet analogin_a0.c Interesting
-
-### Basic SPI
-@snippet spi_mcp4261.c Interesting
-
## Supported platforms
-- Galileo (Fab D)
+Specific platform information for supported platforms is documented here:
+
+- @ref galileorevd
### ENV RECOMENDATIONS
@@ -60,15 +47,11 @@ cmake, libm and pthreads are technically required to compile.
## COMPILING
-mkdir build/
-cmake -i ..
-make
+More information on compiling is @ref building page
-## DEVELOPMENT
+## CONTRIBUTING
-Please fork the code on github and then send pull requests. Please avoid merges
-in your forks. I will also accept patches sent in git style with signoffs to
-brendan.le.foll@intel.com
+Please see the @ref contributing page
## API Changelog
diff --git a/api/aio.h b/api/aio.h
index 47d9ed3..4513e24 100644
--- a/api/aio.h
+++ b/api/aio.h
@@ -25,8 +25,12 @@
#pragma once
/** @file
*
- * This file defines the aio (analog in) interface for libmaa
+ * @brief Analog input/output
*
+ * AIO is the anlog input & output interface to libmaa. It is used to read or
+ * set the voltage applied to an AIO pin.
+ *
+ * @snippet analogin_a0.c Interesting
*/
#ifdef __cplusplus
@@ -44,7 +48,8 @@ extern "C" {
#define ADC_SUPPORTED_RESOLUTION_BITS (10)
/**
- * Opaque pointer definition to the internal struct _aio
+ * Opaque pointer definition to the internal struct _aio. This context refers
+ * to one single AIO pin on the board.
*/
typedef struct _aio* maa_aio_context;
diff --git a/api/gpio.h b/api/gpio.h
index b371154..14e6e09 100644
--- a/api/gpio.h
+++ b/api/gpio.h
@@ -26,8 +26,15 @@
/** @file
*
- * This file defines the gpio interface for libmaa
+ * @brief General Purpose IO
*
+ * GPIO is the General Purpose IO interface to libmaa. It's features depends on
+ * the board type used, it can use gpiolibs (exported via a kernel module
+ * through sysfs), or memory mapped IO via a /dev/uio device or /dev/mem
+ * depending again on the board configuratio, or memory mapped IO via a
+ * /dev/uio device or /dev/mem depending again on the board configuration.
+ *
+ * @snippet gpio_read6.c Interesting
*/
#ifdef __cplusplus
diff --git a/api/i2c.h b/api/i2c.h
index 360f78a..86c9f2f 100644
--- a/api/i2c.h
+++ b/api/i2c.h
@@ -26,8 +26,15 @@
/** @file
*
- * This file defines the i2c interface for libmaa
+ * @brief Inter-Integrated Circuit
*
+ * This file defines the i2c/Iic interface for libmaa. A context represents a
+ * bus and that bus may contain multiple addresses or i2c slaves. It is
+ * considered best practice to make sure the address is correct before doing
+ * any calls on i2c, in case another application or even thread changed the
+ * addres on that bus. Multiple instances of the same bus can exist.
+ *
+ * @snippet i2c_HMC5883L.c Interesting
*/
#ifdef __cplusplus
diff --git a/api/pwm.h b/api/pwm.h
index dc76590..fce45c8 100644
--- a/api/pwm.h
+++ b/api/pwm.h
@@ -26,8 +26,14 @@
/** @file
*
- * This file defines the pwm interface for libmaa
+ * @brief Pulse Width Modulation module
*
+ * PWM is the Pulse Width Modulation interface to libmaa. It allows the
+ * generation of a signal on a pin. Some boards may have higher or lower levels
+ * of resolution so make sure you check the board & pin you are using before
+ * hand.
+ *
+ * @snippet cycle-pwm3.c Interesting
*/
#ifdef __cplusplus
diff --git a/api/spi.h b/api/spi.h
index a4223c4..a1d7bea 100644
--- a/api/spi.h
+++ b/api/spi.h
@@ -25,9 +25,12 @@
#pragma once
/** @file
+ *
+ * @brief System Packet Interface
*
* This file defines the spi interface for libmaa
*
+ * @snippet spi_mcp4261.c Interesting
*/
#ifdef __cplusplus
diff --git a/docs/building.md b/docs/building.md
new file mode 100644
index 0000000..923610a
--- /dev/null
+++ b/docs/building.md
@@ -0,0 +1,27 @@
+Building libmaa {#building}
+===============
+
+libmaa uses cmake in order to make compilation relatively painless. Cmake runs
+build out of tree so the recommended way is to clone from git and make a build/ directory.
+
+~~~~~~~~~~~~~{.sh}
+mkdir build
+cd build
+cmake ..
+make
+~~~~~~~~~~~~~
+
+Our cmake configure has a number of options, `cmake -i` will ask you all sorts
+of interesting questions, you can disable swig modules, build documentation
+etc...
+
+Few recommended options:
+Changing install path from /usr/local to /usr
+-DCMAKE_INSTALL_PREFIX:PATH=/usr
+
+Building debug build:
+-DCMAKE_BUILD_TYPE=DEBUG
+
+Using clang instead of gcc:
+ -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang
+
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 0000000..f295473
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,17 @@
+Contributing to libmaa {#contributing}
+======================
+
+libmaa is an opensource project and we are actively looking for people to help
+with:
+
+- Writing platform supports for all types of embedded boards running linux
+- People to write cool samples
+- People to extend the functionality
+
+The recommended method to contribute is to fork on github, and then send pull
+requests to the main project. Questions can be also be asked and issues raised
+on github.
+
+If you'd rather not use github you are more than welcome to send git formatted
+patches to brendan.le.foll@intel.com.
+
diff --git a/docs/galileorevd.md b/docs/galileorevd.md
new file mode 100644
index 0000000..dca6174
--- /dev/null
+++ b/docs/galileorevd.md
@@ -0,0 +1,10 @@
+Galileo Rev D {#galileorevd}
+=============
+
+Galileo is a microcontroller board based on the Intel® Quark SoC X1000
+Application Processor, a 32-bit Intel Pentium-class system on a chip.
+
+The rev D board has the following limitations in libmaa:
+
+- gpio register access via /dev/uio is limited to pin2 and 3
+- gpio interupts will only work on GPIO_EDGE_BOTH
diff --git a/examples/analogin_a0.c b/examples/analogin_a0.c
index 24f44d5..a543bd2 100644
--- a/examples/analogin_a0.c
+++ b/examples/analogin_a0.c
@@ -23,7 +23,7 @@
*/
#include
-
+//! [Interesting]
#include "aio.h"
int main ()
@@ -31,7 +31,6 @@ int main ()
maa_aio_context adc_a0;
uint16_t adc_value = 0;
-//! [Interesting]
adc_a0 = maa_aio_init(0);
if (adc_a0 == NULL) {
return 1;
@@ -43,7 +42,7 @@ int main ()
}
maa_aio_close(adc_a0);
-//! [Interesting]
return MAA_SUCCESS;
}
+//! [Interesting]
diff --git a/examples/hellomaa.c b/examples/hellomaa.c
index 69d6c4b..b9ed70a 100644
--- a/examples/hellomaa.c
+++ b/examples/hellomaa.c
@@ -23,14 +23,13 @@
*/
#include "stdio.h"
-
+//! [Interesting]
#include "maa.h"
int
main(int argc, char **argv)
{
-//! [Interesting]
fprintf(stdout, "hello maa\n Version: %s\n", maa_get_version());
return 0;
-//! [Interesting]
}
+//! [Interesting]