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

Minor documentation fixes - change \note entries to \warning where appropriate and remove/update old documentation.

Browse source
This commit is contained in:
Dean Camera 2012-02-24 20:25:36 +00:00
parent 5561524a8f
commit e406140f11
32 changed files with 134 additions and 158 deletions
Download patch file Download diff file Expand all files Collapse all files

24
LUFA/Drivers/USB/Core/AVR8/Device_AVR8.h
View file

@ -89,7 +89,7 @@
* \n
*
* \note Restrictions apply on the number, size and type of endpoints which can be used
* when running in low speed mode - refer to the USB 2.0 specification.
* when running in low speed mode - please refer to the USB 2.0 specification.
*/
#define USB_DEVICE_OPT_LOWSPEED (1 << 0)
#endif
@ -138,16 +138,16 @@
* Typically, this is implemented so that HID devices (mice, keyboards, etc.) can wake up the
* host computer when the host has suspended all USB devices to enter a low power state.
*
* \note This macro should only be used if the device has indicated to the host that it
* supports the Remote Wakeup feature in the device descriptors, and should only be
* issued if the host is currently allowing remote wakeup events from the device (i.e.,
* the \ref USB_Device_RemoteWakeupEnabled flag is set). When the \c NO_DEVICE_REMOTE_WAKEUP
* compile time option is used, this macro is unavailable.
* \n\n
* \attention This function should only be used if the device has indicated to the host that it
* supports the Remote Wakeup feature in the device descriptors, and should only be
* issued if the host is currently allowing remote wakeup events from the device (i.e.,
* the \ref USB_Device_RemoteWakeupEnabled flag is set). When the \c NO_DEVICE_REMOTE_WAKEUP
* compile time option is used, this function is unavailable.
* \n\n
*
* \note The USB clock must be running for this function to operate. If the stack is initialized with
* the \ref USB_OPT_MANUAL_PLL option enabled, the user must ensure that the PLL is running
* before attempting to call this function.
* \attention The USB clock must be running for this function to operate. If the stack is initialized with
* the \ref USB_OPT_MANUAL_PLL option enabled, the user must ensure that the PLL is running
* before attempting to call this function.
*
* \see \ref Group_StdDescriptors for more information on the RMWAKEUP feature and device descriptors.
*/
@ -170,7 +170,7 @@
* \ref EVENT_USB_Device_StartOfFrame() event to fire once per millisecond, synchronized to the USB bus,
* at the start of each USB frame when enumerated in device mode.
*
* \note Not available when the \c NO_SOF_EVENTS compile time token is defined.
* \note This function is not available when the \c NO_SOF_EVENTS compile time token is defined.
*/
static inline void USB_Device_EnableSOFEvents(void) ATTR_ALWAYS_INLINE;
static inline void USB_Device_EnableSOFEvents(void)
@ -181,7 +181,7 @@
/** Disables the device mode Start Of Frame events. When disabled, this stops the firing of the
* \ref EVENT_USB_Device_StartOfFrame() event when enumerated in device mode.
*
* \note Not available when the \c NO_SOF_EVENTS compile time token is defined.
* \note This function is not available when the \c NO_SOF_EVENTS compile time token is defined.
*/
static inline void USB_Device_DisableSOFEvents(void) ATTR_ALWAYS_INLINE;
static inline void USB_Device_DisableSOFEvents(void)

26
LUFA/Drivers/USB/Core/AVR8/Endpoint_AVR8.h
View file

@ -171,8 +171,8 @@
/** Retrieves the maximum bank size in bytes of a given endpoint.
*
* \note This macro will only work correctly on endpoint indexes that are compile-time constants
* defined by the preprocessor.
* \attention This macro will only work correctly on endpoint indexes that are compile-time constants
* defined by the preprocessor.
*
* \param[in] EPIndex Endpoint number, a value between 0 and (\ref ENDPOINT_TOTAL_ENDPOINTS - 1)
*/
@ -180,8 +180,8 @@
/** Retrieves the total number of banks supported by the given endpoint.
*
* \note This macro will only work correctly on endpoint indexes that are compile-time constants
* defined by the preprocessor.
* \attention This macro will only work correctly on endpoint indexes that are compile-time constants
* defined by the preprocessor.
*
* \param[in] EPIndex Endpoint number, a value between 0 and (\ref ENDPOINT_TOTAL_ENDPOINTS - 1)
*/
@ -245,12 +245,11 @@
* More banks uses more USB DPRAM, but offers better performance. Isochronous type
* endpoints <b>must</b> have at least two banks.
*
* \note When the \c ORDERED_EP_CONFIG compile time option is used, Endpoints <b>must</b> be configured in
* ascending order, or bank corruption will occur.
* \n\n
* \attention When the \c ORDERED_EP_CONFIG compile time option is used, Endpoints <b>must</b> be configured in
* ascending order, or bank corruption will occur.
*
* \note Different endpoints may have different maximum packet sizes based on the endpoint's index - refer to
* the chosen microcontroller model's datasheet to determine the maximum bank size for each endpoint.
* \note Different endpoints may have different maximum packet sizes based on the endpoint's index - please
* refer to the chosen microcontroller model's datasheet to determine the maximum bank size for each endpoint.
* \n\n
*
* \note The default control endpoint should not be manually configured by the user application, as
@ -278,9 +277,6 @@
}
/** Indicates the number of bytes currently stored in the current endpoint's selected bank.
*
* \note The return width of this function may differ, depending on the maximum endpoint bank size
* of the selected AVR model.
*
* \ingroup Group_EndpointRW_AVR8
*
@ -835,8 +831,8 @@
* \c FIXED_CONTROL_ENDPOINT_SIZE token - it is recommended that the \c FIXED_CONTROL_ENDPOINT_SIZE token
* be used in the device descriptors to ensure this.
*
* \note This variable should be treated as read-only in the user application, and never manually
* changed in value.
* \attention This variable should be treated as read-only in the user application, and never manually
* changed in value.
*/
#if (!defined(FIXED_CONTROL_ENDPOINT_SIZE) || defined(__DOXYGEN__))
extern uint8_t USB_Device_ControlEndpointSize;
@ -848,6 +844,8 @@
/** Completes the status stage of a control transfer on a CONTROL type endpoint automatically,
* with respect to the data direction. This is a convenience function which can be used to
* simplify user control request handling.
*
* \note This routine should not be called on non CONTROL type endpoints.
*/
void Endpoint_ClearStatusStage(void);

8
LUFA/Drivers/USB/Core/AVR8/Host_AVR8.h
View file

@ -146,7 +146,7 @@
* \ref EVENT_USB_Host_StartOfFrame() event to fire once per millisecond, synchronized to the USB bus,
* at the start of each USB frame when a device is enumerated while in host mode.
*
* \note Not available when the \c NO_SOF_EVENTS compile time token is defined.
* \note This function is not available when the \c NO_SOF_EVENTS compile time token is defined.
*/
static inline void USB_Host_EnableSOFEvents(void) ATTR_ALWAYS_INLINE;
static inline void USB_Host_EnableSOFEvents(void)
@ -157,7 +157,7 @@
/** Disables the host mode Start Of Frame events. When disabled, this stops the firing of the
* \ref EVENT_USB_Host_StartOfFrame() event when enumerated in host mode.
*
* \note Not available when the NO_SOF_EVENTS compile time token is defined.
* \note This function is not available when the \c NO_SOF_EVENTS compile time token is defined.
*/
static inline void USB_Host_DisableSOFEvents(void) ATTR_ALWAYS_INLINE;
static inline void USB_Host_DisableSOFEvents(void)
@ -203,8 +203,8 @@
* device until the bus has been resumed. This stops the transmission of the 1MS Start Of Frame
* messages to the device.
*
* \note While the USB bus is suspended, all USB interrupt sources are also disabled; this means that
* some events (such as device disconnections) will not fire until the bus is resumed.
* \attention While the USB bus is suspended, all USB interrupt sources are also disabled; this means that
* some events (such as device disconnections) will not fire until the bus is resumed.
*/
static inline void USB_Host_SuspendBus(void) ATTR_ALWAYS_INLINE;
static inline void USB_Host_SuspendBus(void)

12
LUFA/Drivers/USB/Core/AVR8/Pipe_AVR8.h
View file

@ -192,9 +192,6 @@
/* Inline Functions: */
/** Indicates the number of bytes currently stored in the current pipes's selected bank.
*
* \note The return width of this function may differ, depending on the maximum pipe bank size
* of the selected AVR model.
*
* \ingroup Group_PipeRW_AVR8
*
@ -807,8 +804,8 @@
* descriptor once the USB interface is initialized into host mode and a device is attached
* to the USB bus.
*
* \note This variable should be treated as read-only in the user application, and never manually
* changed in value.
* \attention This variable should be treated as read-only in the user application, and never manually
* changed in value.
*/
extern uint8_t USB_Host_ControlPipeSize;
@ -842,9 +839,8 @@
* uses more USB DPRAM, but offers better performance. Isochronous type pipes <b>must</b>
* have at least two banks.
*
* \note When the \c ORDERED_EP_CONFIG compile time option is used, Pipes <b>must</b> be configured in ascending order,
* or bank corruption will occur.
* \n\n
* \attention When the \c ORDERED_EP_CONFIG compile time option is used, Pipes <b>must</b> be configured in ascending order,
* or bank corruption will occur.
*
* \note Certain microcontroller model's pipes may have different maximum packet sizes based on the pipe's
* index - refer to the chosen microcontroller's datasheet to determine the maximum bank size for each pipe.

11
LUFA/Drivers/USB/Core/AVR8/USBController_AVR8.h
View file

@ -227,7 +227,7 @@
* function prototype.
* \n\n
*
* \note To reduce the FLASH requirements of the library if only fixed settings are are required,
* \note To reduce the FLASH requirements of the library if only fixed settings are required,
* the options may be set statically in the same manner as the mode (see the Mode parameter of
* this function). To statically set the USB options, pass in the \c USE_STATIC_OPTIONS token,
* defined to the appropriate options masks. When the options are statically set, this
@ -271,9 +271,8 @@
/** Indicates the mode that the USB interface is currently initialized to, a value from the
* \ref USB_Modes_t enum.
*
* \note This variable should be treated as read-only in the user application, and never manually
* changed in value.
* \n\n
* \attention This variable should be treated as read-only in the user application, and never manually
* changed in value.
*
* \note When the controller is initialized into UID auto-detection mode, this variable will hold the
* currently selected USB mode (i.e. \ref USB_MODE_Device or \ref USB_MODE_Host). If the controller
@ -293,8 +292,8 @@
/** Indicates the current USB options that the USB interface was initialized with when \ref USB_Init()
* was called. This value will be one of the \c USB_MODE_* masks defined elsewhere in this module.
*
* \note This variable should be treated as read-only in the user application, and never manually
* changed in value.
* \attention This variable should be treated as read-only in the user application, and never manually
* changed in value.
*/
extern volatile uint8_t USB_Options;
#elif defined(USE_STATIC_OPTIONS)