ahoneybun/qmk_firmware
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

More documentation changes for better module-level documentation rather than file-level documentation.

Browse source
This commit is contained in:
Dean Camera 2009-04-17 05:04:21 +00:00
parent 6380d057f8
commit d38fa49cb6
61 changed files with 414 additions and 322 deletions
Download patch file Download diff file Expand all files Collapse all files

7
LUFA/Drivers/Board/ATAVRUSBRF01/HWB.h
View file

@ -36,12 +36,6 @@
* dispatch header located in LUFA/Drivers/Board/HWB.h.
*/
/** \ingroup Group_HWB
* @defgroup Group_HWB_ATAVRUSBRF01 ATAVRUSBRF01
*
* @{
*/
#ifndef __HWB_ATAVRUSBRF01_H__
#define __HWB_ATAVRUSBRF01_H__
@ -84,4 +78,3 @@
#endif
/** @} */

8
LUFA/Drivers/Board/Dataflash.h
View file

@ -43,8 +43,16 @@
/** \ingroup Group_BoardDrivers
* @defgroup Group_Dataflash Dataflash Driver - LUFA/Drivers/Board/Dataflash.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - None
*
* \section Module Description
* Functions, macros, variables, enums and types related to the control of board Dataflash ICs.
*
* If the BOARD value is set to BOARD_USER, this will include the /Board/Dataflash.h file in the user project
* directory. Otherwise, it will include the appropriate built in board driver header file.
*
* @{
*/

8
LUFA/Drivers/Board/HWB.h
View file

@ -43,8 +43,16 @@
/** \ingroup Group_BoardDrivers
* @defgroup Group_HWB HWB Driver - LUFA/Drivers/Board/HWB.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - None
*
* \section Module Description
* Functions, macros, variables, enums and types related to the control of board HWB.
*
* If the BOARD value is set to BOARD_USER, this will include the /Board/Dataflash.h file in the user project
* directory. Otherwise, it will include the appropriate built in board driver header file.
*
* @{
*/

8
LUFA/Drivers/Board/Joystick.h
View file

@ -43,8 +43,16 @@
/** \ingroup Group_BoardDrivers
* @defgroup Group_Joystick Joystick Driver - LUFA/Drivers/Board/Joystick.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - None
*
* \section Module Description
* Functions, macros, variables, enums and types related to the control of board joystick.
*
* If the BOARD value is set to BOARD_USER, this will include the /Board/Dataflash.h file in the user project
* directory. Otherwise, it will include the appropriate built in board driver header file.
*
* @{
*/

8
LUFA/Drivers/Board/LEDs.h
View file

@ -43,8 +43,16 @@
/** \ingroup Group_BoardDrivers
* @defgroup Group_LEDs LEDs Driver - LUFA/Drivers/Board/LEDs.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - None
*
* \section Module Description
* Functions, macros, variables, enums and types related to the control of board LEDs.
*
* If the BOARD value is set to BOARD_USER, this will include the /Board/Dataflash.h file in the user project
* directory. Otherwise, it will include the appropriate built in board driver header file.
*
* @{
*/

7
LUFA/Drivers/Board/STK525/HWB.h
View file

@ -36,12 +36,6 @@
* dispatch header located in LUFA/Drivers/Board/HWB.h.
*/
/** \ingroup Group_HWB
* @defgroup Group_HWB_STK525 STK525
*
* @{
*/
#ifndef __HWB_STK525_H__
#define __HWB_STK525_H__
@ -84,4 +78,3 @@
#endif
/** @} */

8
LUFA/Drivers/Board/STK526/HWB.h
View file

@ -36,12 +36,6 @@
* dispatch header located in LUFA/Drivers/Board/HWB.h.
*/
/** \ingroup Group_HWB
* @defgroup Group_HWB_STK526 STK526
*
* @{
*/
#ifndef __HWB_STK526_H__
#define __HWB_STK526_H__
@ -83,5 +77,3 @@
#endif
#endif
/** @} */

5
LUFA/Drivers/Board/Temperature.h
View file

@ -36,6 +36,11 @@
/** \ingroup Group_BoardDrivers
* @defgroup Group_Temperature Temperature Driver - LUFA/Drivers/Board/Temperature.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/Board/Temperature.c
*
* \section Module Description
* Functions, macros, variables, enums and types related to the control of board temperature sensors.
*
* @{

7
LUFA/Drivers/Board/USBKEY/HWB.h
View file

@ -36,12 +36,6 @@
* dispatch header located in LUFA/Drivers/Board/HWB.h.
*/
/** \ingroup Group_HWB
* @defgroup Group_HWB_USBKEY USBKEY
*
* @{
*/
#ifndef __HWB_USBKEY_H__
#define __HWB_USBKEY_H__
@ -84,4 +78,3 @@
#endif
/** @} */

18
LUFA/Drivers/Misc/TerminalCodes.h
View file

@ -33,6 +33,18 @@
* ANSI terminal compatible escape sequences. These escape sequences are designed to be concatenated with existing
* strings to modify their display on a compatible terminal application.
*
*/
/** \ingroup Group_MiscDrivers
* @defgroup Group_Terminal ANSI Terminal Escape Codes - LUFA/Drivers/Misc/TerminalCodes.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - None
*
* \section 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 code then equate to empty strings).
@ -41,12 +53,6 @@
* \code
* printf("Some String, " ESC_BOLD_ON " Some bold string");
* \endcode
*/
/** \ingroup Group_MiscDrivers
* @defgroup Group_Terminal ANSI Terminal Escape Codes - LUFA/Drivers/Misc/TerminalCodes.h
*
* Escape code macros for ANSI compliant text terminals.
*
* @{
*/

34
LUFA/Drivers/Peripheral/ADC.h
View file

@ -36,8 +36,15 @@
* currently selected AVR model.
*/
/** \ingroup Group_SubsystemDrivers
/** \ingroup Group_PeripheralDrivers
* @defgroup Group_ADC ADC Driver - LUFA/Drivers/Peripheral/ADC.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - None
*
* \section Module Description
* Functions, macros, variables, enums and types related to the setup of a the ADC subsystem.
*/
#ifndef __ADC_H__
@ -58,30 +65,5 @@
#else
#error "ADC is not available for the currently selected AVR model."
#endif
/* Public Interface - May be used in end-application: */
/* Inline Functions: */
/** Starts the reading of the given channel, but does not wait until the conversion has completed.
* Once executed, the conversion status can be determined via the ADC_IsReadingComplete() macro and
* the result read via the ADC_GetResult() macro.
*
* \param MUXMask Mask comprising of an ADC channel number, reference mask and adjustment mask
*/
static inline void ADC_StartReading(const uint8_t MUXMask);
/** Performs a complete single reading from channel, including a polling spinloop to wait for the
* conversion to complete, and the returning of the converted value.
*
* \param MUXMask Mask comprising of an ADC channel number, reference mask and adjustment mask
*/
static inline uint16_t ADC_GetChannelReading(const uint8_t MUXMask) ATTR_WARN_UNUSED_RESULT;
/** Configures the given ADC channel, ready for ADC conversions. This function sets the
* associated port pin as an input and disables the digital portion of the I/O to reduce
* power consumption.
*
* \param Channel ADC channel number to set up for conversions
*/
static inline void ADC_SetupChannel(const uint8_t Channel);
#endif

7
LUFA/Drivers/Peripheral/SPI.h
View file

@ -33,9 +33,14 @@
* Hardware SPI subsystem driver for the supported USB AVRs models.
*/
/** \ingroup Group_SubsystemDrivers
/** \ingroup Group_PeripheralDrivers
* @defgroup Group_SPI SPI Driver - LUFA/Drivers/Peripheral/SPI.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - None
*
* \section Module Description
* Functions, macros, variables, enums and types related to the setup of a the SPI port.
*
* @{

23
LUFA/Drivers/Peripheral/Serial.h
View file

@ -33,9 +33,14 @@
* Driver for the USART subsystem on supported USB AVRs.
*/
/** \ingroup Group_SubsystemDrivers
/** \ingroup Group_PeripheralDrivers
* @defgroup Group_Serial Serial USART Driver - LUFA/Drivers/Peripheral/Serial.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/Peripheral/Serial.c
*
* \section Module Description
* Functions, macros, variables, enums and types related to the setup of the USART for serial communications.
*
* @{
@ -59,11 +64,6 @@
/* Public Interface - May be used in end-application: */
/* Macros: */
/** Indicates whether a character has been received through the USART - boolean false if no character
* has been received, or non-zero if a character is waiting to be read from the reception buffer.
*/
#define Serial_IsCharReceived() ((UCSR1A & (1 << RXC1)) ? true : false)
/** Macro for calculating the baud value from a given baud rate when the U2X (double speed) bit is
* not set.
*/
@ -74,6 +74,17 @@
*/
#define SERIAL_2X_UBBRVAL(baud) (((F_CPU / 8) / baud) - 1)
/* Psuedo-Functions: */
#if defined(__DOXYGEN__)
/** Indicates whether a character has been received through the USART.
*
* \return Boolean true if a character has been received, false otherwise
*/
static inline bool Serial_IsCharReceived(void);
#else
#define Serial_IsCharReceived() ((UCSR1A & (1 << RXC1)) ? true : false)
#endif
/* Function Prototypes: */
/** Initializes the USART, ready for serial data transmission and reception.
*

12
LUFA/Drivers/Peripheral/SerialStream.h
View file

@ -35,11 +35,17 @@
* USART.
**/
/** \ingroup Group_SubsystemDrivers
/** \ingroup Group_PeripheralDrivers
* @defgroup Group_SerialStream Serial Stream Driver - LUFA/Drivers/Peripheral/SerialStream.h
*
* Functions, macros, variables, enums and types related to the setup of a serial stream, so that standard printf and other
* C stream functions can be used on the serial port.
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/Peripheral/SerialStream.c
*
* \section Module Description
* Serial stream driver for the USART subsystem on supported USB AVRs. This makes use of the functions in the
* regular USART driver, but allows the avr-libc standard stream functions (printf, puts, etc.) to work with the
* USART.
*
* @{
*/

6
LUFA/Drivers/USB/Class/ConfigDescriptor.c
View file

@ -28,6 +28,10 @@
this software.
*/
#include "../HighLevel/USBMode.h"
#if defined(USB_CAN_BE_HOST)
#include "ConfigDescriptor.h"
uint8_t USB_Host_GetDeviceConfigDescriptor(uint16_t* const ConfigSizePtr, void* BufferPtr)
@ -138,3 +142,5 @@ uint8_t USB_Host_GetNextDescriptorComp_P(uint16_t* BytesRem, uint8_t** CurrConfi
return Descriptor_Search_Comp_EndOfDescriptor;
}
#endif

15
LUFA/Drivers/USB/Class/HIDParser.h
View file

@ -33,7 +33,14 @@
* USB Human Interface Device (HID) Class report descriptor processing routines. This file allows for the easy
* parsing of the complex HID report descriptor, which describes the data that the device transmits to the host.
*
* The processed report is presented back to the user application as a flat structure containing each report
*/
/** \ingroup Group_USB
* @defgroup Group_HIDParser HID Report Parser
*
* 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
* item's IN, OUT and FEATURE (if desired) items along with each item's attributes.
*
* This library portion also allows for easy setting and retrieval of data from a HID report, including devices
@ -43,12 +50,6 @@
* to save on memory. This can be overridden by defining the HID_ENABLE_FEATURE_PROCESSING or
* HID_INCLUDE_CONSTANT_DATA_ITEMS tokens in the user project makefile, passing them to the compiler via the -D
* switch.
*/
/** \ingroup Group_USB
* @defgroup Group_HIDParser HID Report Parser
*
* Functions, macros, variables, enums and types related to the parsing of HID class device report descriptors.
*
* @{
*/

17
LUFA/Drivers/USB/HighLevel/Events.h
View file

@ -28,22 +28,19 @@
this software.
*/
/** Library events module. This module contains macros and functions relating to the management of library
* events, which are small pieces of code similar to ISRs which are run when a given condition is met. Each
* event can be fired from multiple places in the user or library code, which may or may not be inside an ISR,
* thus each handler should be written to be as small and fast as possible to prevent possible problems.
/** \ingroup Group_USB
* @defgroup Group_Events USB Events
*
* This module contains macros and functions relating to the management of library events, which are small
* pieces of code similar to ISRs which are run when a given condition is met. Each event can be fired from
* multiple places in the user or library code, which may or may not be inside an ISR, thus each handler
* should be written to be as small and fast as possible to prevent possible problems.
*
* Events can be hooked by the user application using the EVENT_HANDLER() and HANDLES_EVENT() macros. If an
* event with no associated handler is fired within the library, it by default fires an internal empty stub
* function. This is achieved through the use of the GCC compiler's "alias" attribute.
*
* Each event must only have one associated event handler, but can be raised by multiple sources.
*/
/** \ingroup Group_USB
* @defgroup Group_Events USB Events
*
* Functions, macros, variables, enums and types related to the management of events from the USB kernel.
*
* @{
*/

9
LUFA/Drivers/USB/HighLevel/StdDescriptors.h
View file

@ -28,7 +28,8 @@
this software.
*/
/** \file
/** \ingroup Group_USB
* @defgroup Group_Descriptors USB Descriptors
*
* Standard USB device descriptor defines and retrieval routines, for USB devices. This module contains
* structures and macros for the easy creation of standard USB descriptors in USB device projects.
@ -42,12 +43,6 @@
* descriptors will contain elements named identically to the official USB specification. The alternately
* named descriptor elements are placed in the same order inside the descriptor structures as their officially
* named counterparts, thus they can be correlated easily with the official USB specification.
*/
/** \ingroup Group_USB
* @defgroup Group_Descriptors USB Descriptors
*
* Functions, macros, variables, enums and types related to standard USB descriptors.
*
* @{
*/

9
LUFA/Drivers/USB/HighLevel/StdRequestType.h
View file

@ -28,16 +28,11 @@
this software.
*/
/** \file
*
* Contains definitions for the various control request parameters, so that the request details (such as data
* direction, request recipient, etc.) can be extracted via masking.
*/
/** \ingroup Group_USB
* @defgroup Group_StdRequest Standard USB Requests
*
* Functions, macros, variables, enums and types related to standard USB requests to USB devices.
* This module contains definitions for the various control request parameters, so that the request
* details (such as data direction, request recipient, etc.) can be extracted via masking.
*
* @{
*/

11
LUFA/Drivers/USB/HighLevel/StreamCallbacks.h
View file

@ -27,18 +27,13 @@
arising out of or in connection with the use or performance of
this software.
*/
/** \file
*
* Macros and enums for the stream callback routines in Endpoint.h and Pipe.c. This module contains the
* code required to easily set up stream callback functions which can be used to force early abort of a
* stream read/write process.
*/
/** \ingroup Group_USB
* @defgroup Group_StreamCallbacks Endpoint and Pipe Stream Callbacks
*
* Functions, macros, variables, enums and types related to endpoint and pipe stream callback functions.
* Macros and enums for the stream callback routines in Endpoint.h and Pipe.c. This module contains the
* code required to easily set up stream callback functions which can be used to force early abort of a
* stream read/write process.
*
* @{
*/

10
LUFA/Drivers/USB/HighLevel/USBInterrupt.h
View file

@ -28,16 +28,12 @@
this software.
*/
/** \file
*
* Main USB interrupt vector handler. This file manages the main USB interrupt vector, for handling such
* events as VBUS interrupts (on supported USB AVR models), device connections and disconnections, etc.
*/
/** \ingroup Group_USB
* @defgroup Group_USBInterrupt Endpoint and Pipe Interrupts
*
* Functions, macros, variables, enums and types related to endpoint and pipe interrupts.
* Main USB interrupt vector handler. This file manages the main USB interrupt vector, for handling such
* events as VBUS interrupts (on supported USB AVR models), device connections and disconnections, etc.
* as well as providing easy to use macros for the management of the Endpoint/Pipe interrupt vector.
*
* @{
*/

6
LUFA/Drivers/USB/HighLevel/USBTask.h
View file

@ -27,12 +27,6 @@
arising out of or in connection with the use or performance of
this software.
*/
/** \file
*
* Main library USB management task for both Host and Device mode operations. This contains the master
* USB_USBTask task which should be periodically run to service both host and device USB projects.
*/
#ifndef __USBTASK_H__
#define __USBTASK_H__

8
LUFA/Drivers/USB/LowLevel/DevChapter9.h
View file

@ -28,14 +28,6 @@
this software.
*/
/** \file
*
* Module for device mode request processing. This module allows for the processing of standard control
* requests to the default control endpoint while in device mode.
*
* \see Chapter 9 of the USB 2.0 specification.
*/
#ifndef __DEVCHAPTER9_H__
#define __DEVCHAPTER9_H__

9
LUFA/Drivers/USB/LowLevel/Device.h
View file

@ -27,17 +27,12 @@
arising out of or in connection with the use or performance of
this software.
*/
/** \file
*
* USB Device mode related macros and enums. This module contains macros and enums which are used when
* the USB controller is initialized in device mode.
*/
/** \ingroup Group_USB
* @defgroup Group_Device Device Management
*
* Functions, macros, variables, enums and types related to the management of a USB device when in Device mode.
* USB Device mode related macros and enums. This module contains macros and enums which are used when
* the USB controller is initialized in device mode.
*
* @{
*/

9
LUFA/Drivers/USB/LowLevel/Endpoint.h
View file

@ -28,17 +28,12 @@
this software.
*/
/** \file
/** \ingroup Group_USB
* @defgroup Group_EndpointManagement Endpoint Management
*
* Functions, macros and enums related to endpoint management when in USB Device mode. This
* module contains the endpoint management macros, as well as endpoint interrupt and data
* send/recieve functions for various data types.
*/
/** \ingroup Group_USB
* @defgroup Group_EndpointManagement Endpoint Management
*
* Functions, macros, variables, enums and types related to the setup and management of endpoints while in USB Device mode.
*
* @{
*/

9
LUFA/Drivers/USB/LowLevel/Host.h
View file

@ -28,16 +28,11 @@
this software.
*/
/** \file
*
* USB Host mode related macros and enums. This module contains macros and enums which are used when
* the USB controller is initialized in host mode.
*/
/** \ingroup Group_USB
* @defgroup Group_Host Host Management
*
* Functions, macros, variables, enums and types related to the management of a USB host when in Host mode.
* USB Host mode related macros and enums. This module contains macros and enums which are used when
* the USB controller is initialized in host mode.
*
* @{
*/

8
LUFA/Drivers/USB/LowLevel/HostChapter9.h
View file

@ -28,14 +28,6 @@
this software.
*/
/** \file
*
* Module for host mode request processing. This module allows for the transmission of standard, class and
* vendor control requests to the default control endpoint of an attached device while in host mode.
*
* \see Chapter 9 of the USB 2.0 specification.
*/
#ifndef __HOSTCHAPTER9_H__
#define __HOSTCHAPTER9_H__

6
LUFA/Drivers/USB/LowLevel/LowLevel.h
View file

@ -28,12 +28,6 @@
this software.
*/
/** \file
*
* Main low level USB driver. This module manages the low level initialization and shut down of the USB AVR's
* USB interface in either device or (if supported) host mode.
*/
/** \ingroup Group_USB
* @defgroup Group_USBManagement USB Interface Management
*

12
LUFA/Drivers/USB/LowLevel/OTG.h
View file

@ -27,19 +27,13 @@
arising out of or in connection with the use or performance of
this software.
*/
/** \file
*
* Macros for embedded USB hosts with dual role On The Go capabilities, for managing role exchange. OTG
* is a way for two USB dual role devices to talk to one another directly without fixed device/host roles.
*
* \note These macros are only for AVRs which support the OTG protocol, and do not exist for device-only AVRs.
*/
/** \ingroup Group_USB
* @defgroup Group_OTGManagement USB On The Go (OTG) Management
*
* Functions, macros, variables, enums and types related to the setup and management of dual role devices.
* This module contains macros for embedded USB hosts with dual role On The Go capabilities, for managing role
* exchange. OTG is a way for two USB dual role devices to talk to one another directly without fixed device/host
* roles.
*
* @{
*/

18
LUFA/Drivers/USB/LowLevel/Pipe.h
View file

@ -27,18 +27,13 @@
arising out of or in connection with the use or performance of
this software.
*/
/** \file
*
* Functions, macros and enums related to pipe management when in USB Host mode. This
* module contains the pipe management macros, as well as pipe interrupt and data
* send/recieve functions for various data types.
*/
/** \ingroup Group_USB
* @defgroup Group_PipeManagement Pipe Management
*
* Functions, macros, variables, enums and types related to the setup and management of pipes while in USB Device mode.
* This module contains functions, macros and enums related to pipe management when in USB Host mode. This
* module contains the pipe management macros, as well as pipe interrupt and data send/recieve functions
* for various data types.
*
* @{
*/
@ -55,8 +50,11 @@
/** @defgroup Group_PipeControlReq Pipe Control Request Management
*
* Functions, macros, variables, enums and types related to control request management of pipes.
*/
* Module for host mode request processing. This module allows for the transmission of standard, class and
* vendor control requests to the default control endpoint of an attached device while in host mode.
*
* \see Chapter 9 of the USB 2.0 specification.
*/
#ifndef __PIPE_H__
#define __PIPE_H__

19
LUFA/Drivers/USB/USB.h
View file

@ -33,13 +33,26 @@
* Master include file for the library USB functionality. This file should be included in all user projects making
* use of the USB portions of the library, instead of including any headers in the USB/LowLevel or USB/HighLevel
* directories.
*
* Class specific utility files in USB/Class/ must still be included manually, as they are not normally part of
* the USB library unless desired by the library user.
*/
/** @defgroup Group_USB USB - LUFA/Drivers/USB/USB.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/LowLevel/DevChapter9.c
* - LUFA/Drivers/USB/LowLevel/Endpoint.c
* - LUFA/Drivers/USB/LowLevel/Host.c
* - LUFA/Drivers/USB/LowLevel/HostChapter9.c
* - LUFA/Drivers/USB/LowLevel/LowLevel.c
* - LUFA/Drivers/USB/LowLevel/Pipe.c
* - LUFA/Drivers/USB/HighLevel/Events.c
* - LUFA/Drivers/USB/HighLevel/StdDescriptors.c
* - LUFA/Drivers/USB/HighLevel/USBInterrupt.c
* - LUFA/Drivers/USB/HighLevel/USBTask.c
* - LUFA/Drivers/USB/Class/ConfigDescriptor.c
* - LUFA/Drivers/USB/Class/HIDParser.c
*
* \section Module Description
* Functions, macros, variables, enums and types related to the management of USB communications.
*/