Documentation improvements - put driver example code into its own section, fix incorrect and missing section names.

This commit is contained in:
Dean Camera 2010-12-26 14:55:26 +00:00
parent 2073b96d82
commit a8b66f318d
109 changed files with 357 additions and 318 deletions

View file

@ -50,7 +50,7 @@
* The following files must be built with any user project that uses this module:
* - None
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Hardware buttons driver. This provides an easy to use driver for the hardware buttons present on many boards.
* It provides a way to easily configure and check the status of all the buttons on the board so that appropriate
* actions can be taken.
@ -60,7 +60,10 @@
*
* For possible BOARD makefile values, see \ref Group_BoardTypes.
*
* <b>Example Usage:</b>
* \section Sec_ExampleUsage Example Usage
* The following snippet is an example of how this module may be used within a typical
* application.
*
* \code
* // Initialise the button driver before first use
* Buttons_Init();

View file

@ -50,7 +50,7 @@
* The following files must be built with any user project that uses this module:
* - None
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Dataflash driver. This module provides an easy to use interface for the Dataflash ICs located on many boards,
* for the storage of large amounts of data into the Dataflash's non-volatile memory.
*
@ -59,7 +59,10 @@
*
* For possible BOARD makefile values, see \ref Group_BoardTypes.
*
* <b>Example Usage:</b>
* \section Sec_ExampleUsage Example Usage
* The following snippet is an example of how this module may be used within a typical
* application.
*
* \code
* // Initialise the SPI and board Dataflash drivers before first use
* SPI_Init(SPI_SPEED_FCPU_DIV_2 | SPI_ORDER_MSB_FIRST | SPI_SCK_LEAD_FALLING |

View file

@ -50,7 +50,7 @@
* The following files must be built with any user project that uses this module:
* - None
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Hardware Joystick driver. This module provides an easy to use interface to control the hardware digital Joystick
* located on many boards.
*
@ -59,7 +59,10 @@
*
* For possible BOARD makefile values, see \ref Group_BoardTypes.
*
* <b>Example Usage:</b>
* \section Sec_ExampleUsage Example Usage
* The following snippet is an example of how this module may be used within a typical
* application.
*
* \code
* // Initialise the board Joystick driver before first use
* Joystick_Init();

View file

@ -50,7 +50,7 @@
* The following files must be built with any user project that uses this module:
* - None
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Hardware LEDs driver. This provides an easy to use driver for the hardware LEDs present on many boards. It
* provides an interface to configure, test and change the status of all the board LEDs.
*
@ -68,7 +68,10 @@
* compatible code for a board with no LEDs by making a board LED driver (see \ref Page_WritingBoardDrivers)
* which contains only stub functions and defines no LEDs.
*
* <b>Example Usage:</b>
* \section Sec_ExampleUsage Example Usage
* The following snippet is an example of how this module may be used within a typical
* application.
*
* \code
* // Initialise the board LED driver before first use
* LEDs_Init();

View file

@ -41,13 +41,16 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/Board/Temperature.c <i>(Makefile source module name: LUFA_SRC_TEMPERATURE)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Temperature sensor driver. This provides an easy to use interface for the hardware temperature sensor located
* on many boards. It provides an interface to configure the sensor and appropriate ADC channel, plus read out the
* current temperature in degrees C. It is designed for and will only work with the temperature sensor located on the
* official Atmel USB AVR boards, as each sensor has different characteristics.
*
* <b>Example Usage:</b>
* \section Sec_ExampleUsage Example Usage
* The following snippet is an example of how this module may be used within a typical
* application.
*
* \code
* // Initialise the ADC and board temperature sensor drivers before first use
* ADC_Init(ADC_FREE_RUNNING | ADC_PRESCALE_128);

View file

@ -47,7 +47,7 @@
* The following files must be built with any user project that uses this module:
* - None
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Lightweight ring buffer, for fast insertion/deletion. Multiple buffers can be created of
* different sizes to suit different needs.
*
@ -56,7 +56,10 @@
* or deletions) must not overlap. If there is possibility of two or more of the same kind of
* operating occuring at the same point in time, atomic (mutex) locking should be used.
*
* <b>Example Usage:</b>
* \section Sec_ExampleUsage Example Usage
* The following snippet is an example of how this module may be used within a typical
* application.
*
* \code
* // Create the buffer structure and its underlying storage array
* RingBuff_t Buffer;

View file

@ -42,16 +42,22 @@
* The following files must be built with any user project that uses this module:
* - None
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Escape code macros for ANSI compliant text terminals.
*
* \note If desired, the macro DISABLE_TERMINAL_CODES can be defined in the project makefile and passed to the GCC
* compiler via the -D switch to disable the terminal codes without modifying the source, for use with non
* compatible terminals (any terminal codes then equate to empty strings).
*
* <b>Example Usage:</b>
* \section Sec_ExampleUsage Example Usage
* The following snippet is an example of how this module may be used within a typical
* application.
*
* \code
* printf("Some String, " ESC_BOLD_ON " Some bold string");
* printf("Normal String, "
* ESC_BOLD_ON "Bold String, "
* ESC_UNDERLINE_ON "Bold and Underlined String"
* ESC_RESET ESC_FG_BLUE ESC_BG_YELLOW "Normal Blue-on-Yellow String");
* \endcode
*
* @{

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - None
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Hardware ADC driver. This module provides an easy to use driver for the hardware
* ADC present on many AVR models, for the conversion of analogue signals into the
* digital domain.

View file

@ -47,7 +47,10 @@
* \note This file should not be included directly. It is automatically included as needed by the ADC driver
* dispatch header located in LUFA/Drivers/Peripheral/ADC.h.
*
* <b>Example Usage:</b>
* \section Sec_ExampleUsage Example Usage
* The following snippet is an example of how this module may be used within a typical
* application.
*
* \code
* // Initialise the ADC driver before first use
* ADC_Init(ADC_FREE_RUNNING | ADC_PRESCALE_32);

View file

@ -45,7 +45,10 @@
* \note This file should not be included directly. It is automatically included as needed by the TWI driver
* dispatch header located in LUFA/Drivers/Peripheral/TWI.h.
*
* <b>Example Usage:</b>
* \section Sec_ExampleUsage Example Usage
* The following snippet is an example of how this module may be used within a typical
* application.
*
* \code
* // Initialise the TWI driver before first use
* TWI_Init();

View file

@ -41,11 +41,14 @@
* The following files must be built with any user project that uses this module:
* - None
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Driver for the hardware SPI port available on most AVR models. This module provides
* an easy to use driver for the setup of and transfer of data over the AVR's SPI port.
*
* <b>Example Usage:</b>
* \section Sec_ExampleUsage Example Usage
* The following snippet is an example of how this module may be used within a typical
* application.
*
* \code
* // Initialise the SPI driver before first use
* SPI_Init(SPI_SPEED_FCPU_DIV_2 | SPI_ORDER_MSB_FIRST | SPI_SCK_LEAD_FALLING |

View file

@ -41,11 +41,14 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/Peripheral/Serial.c <i>(Makefile source module name: LUFA_SRC_SERIAL)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Hardware serial USART driver. This module provides an easy to use driver for
* the setup of and transfer of data over the AVR's USART port.
*
* <b>Example Usage:</b>
* \section Sec_ExampleUsage Example Usage
* The following snippet is an example of how this module may be used within a typical
* application.
*
* \code
* // Initialise the serial USART driver before first use, with 9600 baud (and no double-speed mode)
* Serial_Init(9600, false);

View file

@ -44,13 +44,16 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/Peripheral/SerialStream.c <i>(Makefile source module name: LUFA_SRC_SERIALSTREAM)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Serial stream driver for the USART subsystem on supported USB AVRs. This makes use of the functions in the
* regular USART driver (see \ref Group_Serial), but allows the avr-libc standard stream functions (printf,
* puts, etc.) to work with the USART. Upon configuration, this will redirect the standard input and output
* streams to the USART.
*
* <b>Example Usage:</b>
* \section Sec_ExampleUsage Example Usage
* The following snippet is an example of how this module may be used within a typical
* application.
*
* \code
* // Initialise the Serial Stream driver before first use, with 9600 baud (and no double-speed mode)
* SerialStream_Init(9600, false);

View file

@ -45,7 +45,7 @@
* - LUFA/Drivers/Peripheral/TWI.c <i>(Makefile source module name: LUFA_SRC_TWI)</i>
*
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Master Mode Hardware TWI driver. This module provides an easy to use driver for the hardware
* TWI present on many AVR models, for the transmission and reception of data on a TWI bus.
*

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Device/Audio.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Audio Class Driver module. This module contains an internal implementation of the USB Audio 1.0 Class, for Device
* USB mode only. User applications can use this class driver instead of implementing the Audio class manually via
* the low-level LUFA APIs.

View file

@ -45,7 +45,7 @@
* - LUFA/Drivers/USB/Class/Device/CDC.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
* - LUFA/Drivers/USB/Class/Host/CDC.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* CDC Class Driver module. This module contains an internal implementation of the USB CDC-ACM class Virtual Serial
* Ports, for both Device and Host USB modes. User applications can use this class driver instead of implementing the
* CDC class manually via the low-level LUFA APIs.

View file

@ -40,7 +40,7 @@
/** \ingroup Group_USBClassAudio
* @defgroup Group_USBClassAudioCommon Common Class Definitions
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Constants, Types and Enum definitions that are common to both Device and Host modes for the USB
* Audio 1.0 Class.
*

View file

@ -40,7 +40,7 @@
/** \ingroup Group_USBClassCDC
* @defgroup Group_USBClassCDCCommon Common Class Definitions
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Constants, Types and Enum definitions that are common to both Device and Host modes for the USB
* CDC Class.
*

View file

@ -40,7 +40,7 @@
/** \ingroup Group_USBClassHID
* @defgroup Group_USBClassHIDCommon Common Class Definitions
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Constants, Types and Enum definitions that are common to both Device and Host modes for the USB
* HID Class.
*

View file

@ -40,7 +40,7 @@
/** \ingroup Group_USBClassMIDI
* @defgroup Group_USBClassMIDICommon Common Class Definitions
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Constants, Types and Enum definitions that are common to both Device and Host modes for the USB
* MIDI Class.
*

View file

@ -40,7 +40,7 @@
/** \ingroup Group_USBClassMS
* @defgroup Group_USBClassMSCommon Common Class Definitions
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Constants, Types and Enum definitions that are common to both Device and Host modes for the USB
* Mass Storage Class.
*

View file

@ -40,7 +40,7 @@
/** \ingroup Group_USBClassPrinter
* @defgroup Group_USBClassPrinterCommon Common Class Definitions
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Constants, Types and Enum definitions that are common to both Device and Host modes for the USB
* Printer Class.
*

View file

@ -40,7 +40,7 @@
/** \ingroup Group_USBClassRNDIS
* @defgroup Group_USBClassRNDISCommon Common Class Definitions
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Constants, Types and Enum definitions that are common to both Device and Host modes for the USB
* RNDIS Class.
*

View file

@ -40,7 +40,7 @@
/** \ingroup Group_USBClassSI
* @defgroup Group_USBClassSICommon Common Class Definitions
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Constants, Types and Enum definitions that are common to both Device and Host modes for the USB
* Still Image Class.
*

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Device/Audio.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Device Mode USB Class driver framework interface, for the Audio 1.0 USB Class driver.
*
* @{

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Device/CDC.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Device Mode USB Class driver framework interface, for the CDC USB Class driver.
*
* \note There are several major drawbacks to the CDC-ACM standard USB class, however

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Device/HID.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Device Mode USB Class driver framework interface, for the HID USB Class driver.
*
* @{

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Device/MIDI.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Device Mode USB Class driver framework interface, for the MIDI USB Class driver.
*
* @{

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Device/MassStorage.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Device Mode USB Class driver framework interface, for the Mass Storage USB Class driver.
*
* @{

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Device/RNDIS.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Device Mode USB Class driver framework interface, for the RNDIS USB Class driver.
*
* @{

View file

@ -46,7 +46,7 @@
* - LUFA/Drivers/USB/Class/Host/HID.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
* - LUFA/Drivers/USB/Class/Host/HIDParser.c <i>(Makefile source module name: LUFA_SRC_USB)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* HID Class Driver module. This module contains an internal implementation of the USB HID Class, for both Device
* and Host USB modes. User applications can use this class driver instead of implementing the HID class manually
* via the low-level LUFA APIs.

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Host/CDC.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Host Mode USB Class driver framework interface, for the CDC USB Class driver.
*
* @{

View file

@ -45,7 +45,7 @@
* - LUFA/Drivers/USB/Class/Host/HID.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
* - LUFA/Drivers/USB/Class/Host/HIDParser.c <i>(Makefile source module name: LUFA_SRC_USB)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Host Mode USB Class driver framework interface, for the HID USB Class driver.
*
* @{

View file

@ -43,7 +43,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Host/HIDParser.c <i>(Makefile source module name: LUFA_SRC_USB)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Functions, macros, variables, enums and types related to the parsing of HID class device report descriptors.
*
* The processed HID report is presented back to the user application as a flat structure containing each report

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Host/MIDI.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Host Mode USB Class driver framework interface, for the MIDI USB Class driver.
*
* @{

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Host/MassStorage.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Host Mode USB Class driver framework interface, for the Mass Storage USB Class driver.
*
* @{

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Host/Printer.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Host Mode USB Class driver framework interface, for the Printer USB Class driver.
*
* @{

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Host/RNDIS.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Host Mode USB Class driver framework interface, for the Microsoft RNDIS Ethernet
* USB Class driver.
*

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Host/StillImage.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Host Mode USB Class driver framework interface, for the Still Image USB Class driver.
*
* @{

View file

@ -45,7 +45,7 @@
* - LUFA/Drivers/USB/Class/Device/MIDI.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
* - LUFA/Drivers/USB/Class/Host/MIDI.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* MIDI Class Driver module. This module contains an internal implementation of the USB MIDI Class, for both Device
* and Host USB modes. User applications can use this class driver instead of implementing the MIDI class manually
* via the low-level LUFA APIs.

View file

@ -45,7 +45,7 @@
* - LUFA/Drivers/USB/Class/Device/MassStorage.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
* - LUFA/Drivers/USB/Class/Host/MassStorage.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Mass Storage Class Driver module. This module contains an internal implementation of the USB Mass Storage Class, for both
* Device and Host USB modes. User applications can use this class driver instead of implementing the Mass Storage class
* manually via the low-level LUFA APIs.

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Host/Printer.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Printer Class Driver module. This module contains an internal implementation of the USB Printer Class, for the base
* USB Printer transport layer for USB Host mode only. Note that printers are free to implement whatever printer language
* they choose on top of this (e.g. Postscript), and so this driver exposes low level data transport functions only rather

View file

@ -45,7 +45,7 @@
* - LUFA/Drivers/USB/Class/Device/RNDIS.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
* - LUFA/Drivers/USB/Class/Host/RNDIS.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* RNDIS Class Driver module. This module contains an internal implementation of the Microsoft USB RNDIS Networking
* Class, for both Device and Host USB modes. User applications can use this class driver instead of implementing the
* RNDIS class manually via the low-level LUFA APIs.

View file

@ -44,7 +44,7 @@
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Host/StillImage.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Still Image Class Driver module. This module contains an internal implementation of the USB Still Image Class,
* for USB Host mode only. User applications can use this class driver instead of implementing the Still Image class
* manually via the low-level LUFA APIs.

View file

@ -55,7 +55,7 @@
* - LUFA/Drivers/USB/HighLevel/PipeStream.c <i>(Makefile source module name: LUFA_SRC_USB)</i>
* - LUFA/Drivers/USB/HighLevel/USBTask.c <i>(Makefile source module name: LUFA_SRC_USB)</i>
*
* \section Module Description
* \section Sec_ModDescription Module Description
* Driver and framework for the USB controller hardware on the USB series of AVR microcontrollers. This module
* consists of many submodules, and is designed to provide an easy way to configure and control USB host, device
* or OTG mode USB applications.
@ -139,7 +139,7 @@
* slightly differently, and thus will be explained separately. For information on a specific class driver, read
* the class driver's module documentation.
*
* \subsection SSec_ClassDriverDevice Device Mode Class Drivers
* \subsection Sec_ClassDriverDevice Device Mode Class Drivers
* Implementing a Device Mode Class Driver in a user application requires a number of steps to be followed. Firstly,
* the module configuration and state structure must be added to the project source. These structures are named in a
* similar manner between classes, that of <i>USB_ClassInfo_<b>{Class Name}</b>_Device_t</i>, and are used to hold the
@ -238,7 +238,7 @@
* read and write routines. See each driver's individual documentation for more information on the
* class-specific functions.
*
* \subsection SSec_ClassDriverHost Host Mode Class Drivers
* \subsection Sec_ClassDriverHost Host Mode Class Drivers
* Implementing a Host Mode Class Driver in a user application requires a number of steps to be followed. Firstly,
* the module configuration and state structure must be added to the project source. These structures are named in a
* similar manner between classes, that of <i>USB_ClassInfo_<b>{Class Name}</b>_Host_t</i>, and are used to hold the