Raspberries/mraa
Private
Public Access
2
0
Fork 0
Code Activity

docs: Add docs/ folder with in depth topics as well as DoxygenLayout.xml file

Browse Source 
* C headers now have @briefs and include examples
* Examples have altered 'Interesting' Sections

Signed-off-by: Brendan Le Foll <brendan.le.foll@intel.com>
This commit is contained in:
Brendan Le Foll
2014-05-29 14:51:38 +01:00
parent b9352a9e8c
commit a02923beec
13 changed files with 312 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
Doxyfile.in
View File

@@ -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.

194
DoxygenLayout.xml Normal file
View File

@@ -0,0 +1,194 @@
<doxygenlayout version="1.0">
<!-- Generated by doxygen 1.8.7 -->
<!-- Navigation index tabs for HTML output -->
<navindex>
<tab type="mainpage" visible="yes" title=""/>
<tab type="pages" visible="yes" title="" intro=""/>
<tab type="modules" visible="yes" title="" intro=""/>
<tab type="namespaces" visible="yes" title="">
<tab type="namespacelist" visible="yes" title="" intro=""/>
<tab type="namespacemembers" visible="yes" title="" intro=""/>
</tab>
<tab type="classes" visible="yes" title="">
<tab type="classlist" visible="yes" title="" intro=""/>
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
<tab type="hierarchy" visible="yes" title="" intro=""/>
<tab type="classmembers" visible="yes" title="" intro=""/>
</tab>
<tab type="files" visible="yes" title="">
<tab type="filelist" visible="yes" title="" intro=""/>
<tab type="globals" visible="yes" title="" intro=""/>
</tab>
<tab type="examples" visible="yes" title="" intro=""/>
</navindex>
<!-- Layout definition for a class page -->
<class>
<briefdescription visible="yes"/>
<includes visible="$SHOW_INCLUDE_FILES"/>
<inheritancegraph visible="$CLASS_GRAPH"/>
<collaborationgraph visible="$COLLABORATION_GRAPH"/>
<memberdecl>
<nestedclasses visible="yes" title=""/>
<publictypes title=""/>
<services title=""/>
<interfaces title=""/>
<publicslots title=""/>
<signals title=""/>
<publicmethods title=""/>
<publicstaticmethods title=""/>
<publicattributes title=""/>
<publicstaticattributes title=""/>
<protectedtypes title=""/>
<protectedslots title=""/>
<protectedmethods title=""/>
<protectedstaticmethods title=""/>
<protectedattributes title=""/>
<protectedstaticattributes title=""/>
<packagetypes title=""/>
<packagemethods title=""/>
<packagestaticmethods title=""/>
<packageattributes title=""/>
<packagestaticattributes title=""/>
<properties title=""/>
<events title=""/>
<privatetypes title=""/>
<privateslots title=""/>
<privatemethods title=""/>
<privatestaticmethods title=""/>
<privateattributes title=""/>
<privatestaticattributes title=""/>
<friends title=""/>
<related title="" subtitle=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
<enums title=""/>
<services title=""/>
<interfaces title=""/>
<constructors title=""/>
<functions title=""/>
<related title=""/>
<variables title=""/>
<properties title=""/>
<events title=""/>
</memberdef>
<allmemberslink visible="yes"/>
<usedfiles visible="$SHOW_USED_FILES"/>
<authorsection visible="yes"/>
</class>
<!-- Layout definition for a namespace page -->
<namespace>
<briefdescription visible="yes"/>
<memberdecl>
<nestednamespaces visible="yes" title=""/>
<constantgroups visible="yes" title=""/>
<classes visible="yes" title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
</memberdef>
<authorsection visible="yes"/>
</namespace>
<!-- Layout definition for a file page -->
<file>
<briefdescription visible="no"/>
<includegraph visible="$INCLUDE_GRAPH"/>
<includes visible="$SHOW_INCLUDE_FILES"/>
<detaileddescription title="API Description"/>
<sourcelink visible="yes"/>
<memberdecl>
<classes visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<functions title=""/>
<constantgroups visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<variables title=""/>
<membergroups visible="yes"/>
</memberdecl>
<memberdef>
<inlineclasses title=""/>
<functions title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<variables title=""/>
</memberdef>
<includedbygraph visible="$INCLUDED_BY_GRAPH"/>
<authorsection/>
</file>
<!-- Layout definition for a group page -->
<group>
<briefdescription visible="yes"/>
<groupgraph visible="$GROUP_GRAPHS"/>
<memberdecl>
<nestedgroups visible="yes" title=""/>
<dirs visible="yes" title=""/>
<files visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<classes visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<pagedocs/>
<inlineclasses title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
</memberdef>
<authorsection visible="yes"/>
</group>
<!-- Layout definition for a directory page -->
<directory>
<briefdescription visible="yes"/>
<directorygraph visible="yes"/>
<memberdecl>
<dirs visible="yes"/>
<files visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
</directory>
</doxygenlayout>

45
README.md
View File

@@ -16,37 +16,24 @@ classes directly wrap the C API and provide a near 1:1 mapping of
functionality.
<center>
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" |
</center>
### 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

9
api/aio.h
View File

@@ -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;

9
api/gpio.h
View File

@@ -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

9
api/i2c.h
View File

@@ -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

8
api/pwm.h
View File

@@ -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

3
api/spi.h
View File

@@ -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

27
docs/building.md Normal file
View File

@@ -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

17
docs/contributing.md Normal file
View File

@@ -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.

10
docs/galileorevd.md Normal file
View File

@@ -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

5
examples/analogin_a0.c
View File

@@ -23,7 +23,7 @@
*/
#include <unistd.h>
//! [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]

5
examples/hellomaa.c
View File

@@ -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]