Commit 5e731905 authored by Dean Camera's avatar Dean Camera

Start update of documentation to support possible multiple architectures in...

Start update of documentation to support possible multiple architectures in the future - alter \file documentation to automatically copy in the module documentation where possible.
parent 1daa5e16
......@@ -43,9 +43,6 @@
#define __BUTTONS_USER_H__
/* Includes: */
#include <avr/io.h>
#include <stdbool.h>
// TODO: Add any required includes here
/* Enable C linkage for C++ Compilers: */
......
......@@ -44,8 +44,6 @@
#define __JOYSTICK_USER_H__
/* Includes: */
#include <avr/io.h>
// TODO: Add any required includes here
/* Enable C linkage for C++ Compilers: */
......
......@@ -43,8 +43,6 @@
#define __LEDS_USER_H__
/* Includes: */
#include <avr/io.h>
// TODO: Add any required includes here
/* Enable C linkage for C++ Compilers: */
......
......@@ -31,8 +31,7 @@
/** \file
* \brief Supported architecture defines.
*
* This file contains constants which can be passed to the compiler (via setting the macro ARCH) in the
* user project makefile using the -D option to configure the library drivers.
* \copydetails Group_Architectures
*
* \note Do not include this file directly, rather include the Common.h header file instead to gain this file's
* functionality.
......@@ -40,6 +39,7 @@
/** \ingroup Group_Common
* \defgroup Group_Architectures Hardware Architectures
* \brief Supported architecture defines.
*
* Macros for indicating the chosen hardware architecture to the library. These macros should be used when
* defining the ARCH token to the chosen hardware via the -D switch in the project makefile.
......
......@@ -31,23 +31,23 @@
/** \file
* \brief AVR-GCC special function/variable attribute macros.
*
* This file contains macros for applying GCC specific attributes to functions and variables to control various
* optimiser and code generation features of the compiler. Attributes may be placed in the function prototype
* or variable declaration in any order, and multiple attributes can be specified for a single item via a space
* separated list.
*
* On incompatible versions of GCC or on other compilers, these macros evaluate to nothing unless they are
* critical to the code's function and thus must throw a compiler error when used.
* \copydetails Group_GCCAttributes
*
* \note Do not include this file directly, rather include the Common.h header file instead to gain this file's
* functionality.
*/
/** \ingroup Group_Common
* \defgroup Group_GCCAttr Function/Variable Attributes
* \defgroup Group_GCCAttributes Function/Variable Attributes
* \brief AVR-GCC special function/variable attribute macros.
*
* Macros for easy access GCC function and variable attributes, which can be applied to function prototypes or
* variable attributes.
* This file contains macros for applying GCC specific attributes to functions and variables to control various
* optimiser and code generation features of the compiler. Attributes may be placed in the function prototype
* or variable declaration in any order, and multiple attributes can be specified for a single item via a space
* separated list.
*
* On incompatible versions of GCC or on other compilers, these macros evaluate to nothing unless they are
* critical to the code's function and thus must throw a compiler error when used.
*
* @{
*/
......
......@@ -31,8 +31,7 @@
/** \file
* \brief Supported board hardware defines.
*
* This file contains constants which can be passed to the compiler (via setting the macro BOARD) in the
* user project makefile using the -D option to configure the library board-specific drivers.
* \copydetails Group_BoardTypes
*
* \note Do not include this file directly, rather include the Common.h header file instead to gain this file's
* functionality.
......@@ -40,6 +39,7 @@
/** \ingroup Group_Common
* \defgroup Group_BoardTypes Board Types
* \brief Supported board hardware defines.
*
* Macros for indicating the chosen physical board hardware to the library. These macros should be used when
* defining the BOARD token to the chosen hardware via the -D switch in the project makefile.
......
......@@ -31,11 +31,11 @@
/** \file
* \brief Common library convenience macros and functions.
*
* This file contains macros which are common to all library elements, and which may be useful in user code. It
* also includes other common code headers.
* \copydetails Group_Common
*/
/** \defgroup Group_Common Common Utility Headers - LUFA/Drivers/Common/Common.h
* \brief Common library convenience macros and functions.
*
* Common utility headers containing macros, functions, enums and types which are common to all
* aspects of the library.
......@@ -64,7 +64,8 @@
/* Includes: */
#include <stdint.h>
#include <stdbool.h>
#include <string.h>
#include "Architectures.h"
#include "Attributes.h"
#include "BoardTypes.h"
......@@ -75,6 +76,7 @@
#include <avr/interrupt.h>
#include <avr/pgmspace.h>
#include <avr/eeprom.h>
#include <avr/boot.h>
#include <util/atomic.h>
#include <util/delay.h>
#endif
......@@ -123,7 +125,7 @@
#define MIN(x, y) ((x < y) ? x : y)
#endif
#if (ARCH == ARCH_AVR8)
#if (ARCH == ARCH_AVR8) || defined(__DOXYGEN__)
/** Defines a volatile \c NOP statement which cannot be optimized out by the compiler, and thus can always
* be set as a breakpoint in the resulting code. Useful for debugging purposes, where the optimiser
* removes/reorders code to the point where break points cannot reliably be set.
......
......@@ -30,8 +30,7 @@
/** \file
* \brief Board specific LED driver header for the Adafruit U4 Breakout board.
*
* Board specific LED driver header for the Adafruit U4 Breakout board (http://ladyada.net/products/atmega32u4breakout).
* \copydetails Group_LEDs_ADAFRUITU4
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
......@@ -39,12 +38,10 @@
/** \ingroup Group_LEDs
* \defgroup Group_LEDs_ADAFRUITU4 ADAFRUITU4
* \brief Board specific LED driver header for the Adafruit U4 Breakout board.
*
* Board specific LED driver header for the Adafruit U4 Breakout board (http://ladyada.net/products/atmega32u4breakout).
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
*
* @{
*/
......@@ -52,8 +49,6 @@
#define __LEDS_ADAFRUITU4_H__
/* Includes: */
#include <avr/io.h>
#include "../../../Common/Common.h"
/* Enable C linkage for C++ Compilers: */
......
......@@ -30,8 +30,7 @@
/** \file
* \brief Board specific Buttons driver header for the Atmel ATAVRUSBRF01.
*
* Board specific Buttons driver header for the Atmel ATAVRUSBRF01.
* \copydetails Group_Buttons_ATAVRUSBRF01
*
* \note This file should not be included directly. It is automatically included as needed by the Buttons driver
* dispatch header located in LUFA/Drivers/Board/Buttons.h.
......@@ -39,12 +38,10 @@
/** \ingroup Group_Buttons
* \defgroup Group_Buttons_ATAVRUSBRF01 ATAVRUSBRF01
* \brief Board specific Buttons driver header for the Atmel ATAVRUSBRF01.
*
* Board specific Buttons driver header for the Atmel ATAVRUSBRF01.
*
* \note This file should not be included directly. It is automatically included as needed by the Buttons driver
* dispatch header located in LUFA/Drivers/Board/Buttons.h.
*
* @{
*/
......@@ -52,9 +49,6 @@
#define __BUTTONS_ATAVRUSBRF01_H__
/* Includes: */
#include <avr/io.h>
#include <stdbool.h>
#include "../../../Common/Common.h"
/* Enable C linkage for C++ Compilers: */
......
......@@ -30,8 +30,7 @@
/** \file
* \brief Board specific LED driver header for the Atmel ATAVRUSBRF01.
*
* Board specific LED driver header for the Atmel ATAVRUSBRF01.
* \copydetails Group_LEDs_ATAVRUSBRF01
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
......@@ -39,12 +38,10 @@
/** \ingroup Group_LEDs
* \defgroup Group_LEDs_ATAVRUSBRF01 ATAVRUSBRF01
* \brief Board specific LED driver header for the Atmel ATAVRUSBRF01.
*
* Board specific LED driver header for the Atmel ATAVRUSBRF01.
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
*
* @{
*/
......@@ -52,8 +49,6 @@
#define __LEDS_ATAVRUSBRF01_H__
/* Includes: */
#include <avr/io.h>
#include "../../../Common/Common.h"
/* Enable C linkage for C++ Compilers: */
......
......@@ -30,8 +30,7 @@
/** \file
* \brief Board specific Buttons driver header for the Tempusdictum Benito.
*
* Board specific Buttons driver header for the Tempusdictum Benito (http://dorkbotpdx.org/wiki/benito).
* \copydetails Group_Buttons_BENITO
*
* \note This file should not be included directly. It is automatically included as needed by the Buttons driver
* dispatch header located in LUFA/Drivers/Board/Buttons.h.
......@@ -39,12 +38,10 @@
/** \ingroup Group_Buttons
* \defgroup Group_Buttons_BENITO BENITO
* \brief Board specific Buttons driver header for the Tempusdictum Benito.
*
* Board specific Buttons driver header for the Tempusdictum Benito (http://dorkbotpdx.org/wiki/benito).
*
* \note This file should not be included directly. It is automatically included as needed by the Buttons driver
* dispatch header located in LUFA/Drivers/Board/Buttons.h.
*
* @{
*/
......@@ -52,9 +49,6 @@
#define __BUTTONS_BENITO_H__
/* Includes: */
#include <avr/io.h>
#include <stdbool.h>
#include "../../../Common/Common.h"
/* Enable C linkage for C++ Compilers: */
......
......@@ -30,8 +30,7 @@
/** \file
* \brief Board specific LED driver header for the Tempusdictum Benito.
*
* Board specific LED driver header for the Tempusdictum Benito (http://dorkbotpdx.org/wiki/benito).
* \copydetails Group_LEDs_BENITO
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
......@@ -39,12 +38,10 @@
/** \ingroup Group_LEDs
* \defgroup Group_LEDs_BENITO BENITO
* \brief Board specific LED driver header for the Tempusdictum Benito.
*
* Board specific LED driver header for the Tempusdictum Benito (http://dorkbotpdx.org/wiki/benito).
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
*
* @{
*/
......@@ -52,7 +49,7 @@
#define __LEDS_BENITO_H__
/* Includes: */
#include <avr/io.h>
#include "../../../Common/Common.h"
/* Enable C linkage for C++ Compilers: */
#if defined(__cplusplus)
......
......@@ -30,8 +30,7 @@
/** \file
* \brief Board specific LED driver header for the BLACKCAT USB JTAG.
*
* Board specific LED driver header for the TCNISO Blackcat USB JTAG (http://www.embeddedcomputers.net/products/BlackcatUSB/.
* \copydetails Group_LEDs_BLACKCAT
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
......@@ -39,12 +38,10 @@
/** \ingroup Group_LEDs
* \defgroup Group_LEDs_BLACKCAT BLACKCAT
* \brief Board specific LED driver header for the BLACKCAT USB JTAG.
*
* Board specific LED driver header for the TCNISO Blackcat USB JTAG (http://www.embeddedcomputers.net/products/BlackcatUSB/.
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
*
* @{
*/
......@@ -52,8 +49,6 @@
#define __LEDS_BLACKCAT_H__
/* Includes: */
#include <avr/io.h>
#include "../../../Common/Common.h"
/* Enable C linkage for C++ Compilers: */
......
......@@ -30,8 +30,7 @@
/** \file
* \brief Board specific LED driver header for the Busware BUI.
*
* Board specific LED driver header for the Busware BUI (http://www.busware.de/tiki-index.php?page=BUI).
* \copydetails Group_LEDs_BUI
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
......@@ -39,12 +38,10 @@
/** \ingroup Group_LEDs
* \defgroup Group_LEDs_BUI BUI
* \brief Board specific LED driver header for the Busware BUI.
*
* Board specific LED driver header for the Busware BUI (http://www.busware.de/tiki-index.php?page=BUI).
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
*
* @{
*/
......@@ -52,7 +49,7 @@
#define __LEDS_BUI_H__
/* Includes: */
#include <avr/io.h>
#include "../../../Common/Common.h"
/* Enable C linkage for C++ Compilers: */
#if defined(__cplusplus)
......
......@@ -30,11 +30,7 @@
/** \file
* \brief Board specific Buttons driver header for the Fletchtronics BUMBLEB.
*
* Board specific Buttons driver header for the Fletchtronics BUMBLEB (http://fletchtronics.net/bumble-b).
*
* The BUMBLEB third-party board does not include any on-board peripherals, but does have an officially recommended
* external peripheral layout for buttons, LEDs and a Joystick.
* \copydetails Group_Buttons_BUMBLEB
*
* \note This file should not be included directly. It is automatically included as needed by the Buttons driver
* dispatch header located in LUFA/Drivers/Board/Buttons.h.
......@@ -42,14 +38,12 @@
/** \ingroup Group_Buttons
* \defgroup Group_Buttons_BUMBLEB BUMBLEB
* \brief Board specific Buttons driver header for the Fletchtronics BUMBLEB.
*
* Board specific buttons driver header for the Fletchtronics BUMBLEB (http://fletchtronics.net/bumble-b). The BUMBLEB
* third-party board does not include any on-board peripherals, but does have an officially recommended external peripheral
* layout for buttons, LEDs and a Joystick.
*
* \note This file should not be included directly. It is automatically included as needed by the Buttons driver
* dispatch header located in LUFA/Drivers/Board/Buttons.h.
*
* @{
*/
......@@ -57,9 +51,6 @@
#define __BUTTONS_BUMBLEB_H__
/* Includes: */
#include <avr/io.h>
#include <stdbool.h>
#include "../../../Common/Common.h"
/* Enable C linkage for C++ Compilers: */
......
......@@ -30,11 +30,7 @@
/** \file
* \brief Board specific joystick driver header for the Fletchtronics BUMLEB.
*
* Board specific joystick driver header for the Fletchtronics BUMBLEB (http://fletchtronics.net/bumble-b).
*
* The BUMBLEB third-party board does not include any on-board peripherals, but does have an officially recommended
* external peripheral layout for buttons, LEDs and a Joystick.
* \copydetails Group_Joystick_BUMBLEB
*
* \note This file should not be included directly. It is automatically included as needed by the joystick driver
* dispatch header located in LUFA/Drivers/Board/Joystick.h.
......@@ -42,14 +38,12 @@
/** \ingroup Group_Joystick
* \defgroup Group_Joystick_BUMBLEB BUMBLEB
* \brief Board specific joystick driver header for the Fletchtronics BUMLEB.
*
* Board specific joystick driver header for the Fletchtronics BUMBLEB (http://fletchtronics.net/bumble-b). The BUMBLEB
* third-party board does not include any on-board peripherals, but does have an officially recommended external peripheral
* layout for buttons, LEDs and a Joystick.
*
* \note This file should not be included directly. It is automatically included as needed by the joystick driver
* dispatch header located in LUFA/Drivers/Board/Joystick.h.
*
* @{
*/
......@@ -57,8 +51,6 @@
#define __JOYSTICK_BUMBLEB_H__
/* Includes: */
#include <avr/io.h>
#include "../../../Common/Common.h"
/* Enable C linkage for C++ Compilers: */
......
......@@ -30,11 +30,7 @@
/** \file
* \brief Board specific LED driver header for the Fletchtronics BUMBLEB.
*
* Board specific LED driver header for the Fletchtronics BUMBLEB (http://fletchtronics.net/bumble-b).
*
* The BUMBLEB third-party board does not include any on-board peripherals, but does have an officially recommended
* external peripheral layout for buttons, LEDs and a Joystick.
* \copydetails Group_LEDs_BUMBLEB
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
......@@ -42,14 +38,12 @@
/** \ingroup Group_LEDs
* \defgroup Group_LEDs_BUMBLEB BUMBLEB
* \brief Board specific LED driver header for the Fletchtronics BUMBLEB.
*
* Board specific LED driver header for the Fletchtronics BUMBLEB (http://fletchtronics.net/bumble-b). The BUMBLEB
* third-party board does not include any on-board peripherals, but does have an officially recommended external
* peripheral layout for buttons, LEDs and a Joystick.
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
*
* @{
*/
......@@ -57,8 +51,6 @@
#define __LEDS_BUMBLEB_H__
/* Includes: */
#include <avr/io.h>
#include "../../../Common/Common.h"
/* Enable C linkage for C++ Compilers: */
......
......@@ -30,8 +30,7 @@
/** \file
* \brief Board specific LED driver header for the Busware CULV3.
*
* Board specific LED driver header for the Busware CUL V3 (http://busware.de/tiki-index.php?page=CUL).
* \copydetails Group_LEDs_CULV3
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
......@@ -39,12 +38,10 @@
/** \ingroup Group_LEDs
* \defgroup Group_LEDs_CULV3 CULV3
* \brief Board specific LED driver header for the Busware CULV3.
*
* Board specific LED driver header for the Busware CUL V3 (http://busware.de/tiki-index.php?page=CUL).
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
*
* @{
*/
......@@ -52,9 +49,6 @@
#define __BUTTONS_CULV3_H__
/* Includes: */
#include <avr/io.h>
#include <stdbool.h>
#include "../../../Common/Common.h"
/* Enable C linkage for C++ Compilers: */
......
......@@ -30,8 +30,7 @@
/** \file
* \brief Board specific LED driver header for the Busware CUL V3.
*
* Board specific LED driver header for the Busware CUL V3 (http://busware.de/tiki-index.php?page=CUL).
* \copydetails Group_LEDs_CULV3
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
......@@ -39,12 +38,10 @@
/** \ingroup Group_LEDs
* \defgroup Group_LEDs_CULV3 CULV3
* \brief Board specific LED driver header for the Busware CUL V3.
*
* Board specific LED driver header for the Busware CUL V3 (http://busware.de/tiki-index.php?page=CUL).
*
* \note This file should not be included directly. It is automatically included as needed by the LEDs driver
* dispatch header located in LUFA/Drivers/Board/LEDs.h.
*
* @{
*/
......@@ -52,8 +49,6 @@
#define __LEDS_CULV3_H__
/* Includes: */
#include <avr/io.h>
#include "../../../Common/Common.h"
/* Enable C linkage for C++ Compilers: */
......
......@@ -30,8 +30,7 @@
/** \file
* \brief Board specific Buttons driver header for the Atmel EVK527.
*
* Board specific Buttons driver header for the Atmel EVK527.
* \copydetails Group_Buttons_EVK527
*
* \note This file should not be included directly. It is automatically included as needed by the Buttons driver
* dispatch header located in LUFA/Drivers/Board/Buttons.h.
......@@ -39,12 +38,10 @@
/** \ingroup Group_Buttons
* \defgroup Group_Buttons_EVK527 EVK527
* \brief Board specific Buttons driver header for the Atmel EVK527.
*
* Board specific Buttons driver header for the Atmel EVK527.
*
* \note This file should not be included directly. It is automatically included as needed by the Buttons driver
* dispatch header located in LUFA/Drivers/Board/Buttons.h.
*
* @{
*/
......@@ -52,15 +49,6 @@
#define __BUTTONS_EVK527_H__
/* Includes: */
#include <avr/io.h>
#include <stdbool.h>
#include "../../../Common/Common.h"
/* Includes: */
#include <avr/io.h>
#include <stdbool.h>
#include "../../../Common/Common.h"
/* Enable C linkage for C++ Compilers: */
......
......@@ -30,8 +30,7 @@
/** \file
* \brief Board specific Dataflash driver header for the Atmel EVK527.
*
* Board specific Dataflash driver header for the Atmel EVK527.
* \copydetails Group_Dataflash_EVK527
*
* \note This file should not be included directly. It is automatically included as needed by the dataflash driver
* dispatch header located in LUFA/Drivers/Board/Dataflash.h.
......@@ -39,12 +38,10 @@
/** \ingroup Group_Dataflash
* \defgroup Group_Dataflash_EVK527 EVK527
* \brief Board specific Dataflash driver header for the Atmel EVK527.
*
* Board specific Dataflash driver header for the Atmel EVK527.
*
* \note This file should not be included directly. It is automatically included as needed by the dataflash driver
* dispatch header located in LUFA/Drivers/Board/Dataflash.h.
*
* @{
*/
......
......@@ -30,8 +30,7 @@
/** \file
* \brief Board specific joystick driver header for the Atmel EVK527.
*
* Board specific joystick driver header for the Atmel EVK527.
* \copydetails Group_Joystick_EVK527
*
* \note This file should not be included directly. It is automatically included as needed by the joystick driver
* dispatch header located in LUFA/Drivers/Board/Joystick.h.
......@@ -39,12 +38,10 @@
/** \ingroup Group_Joystick
* \defgroup Group_Joystick_EVK527 EVK527
* \brief Board specific joystick driver header for the Atmel EVK527.
*
* Board specific joystick driver header for the Atmel EVK527.
*
* \note This file should not be included directly. It is automatically included as needed by the joystick driver
* dispatch header located in LUFA/Drivers/Board/Joystick.h.
*
* @{
*/
......@@ -52,8 +49,6 @@
#define __JOYSTICK_EVK527_H__
/* Includes: */
#include <avr/io.h>
#include "../../../Common/Common.h"