From 1f682ca2de8df89e3fef0077b33070cf2c85e798 Mon Sep 17 00:00:00 2001 From: Dean Camera Date: Thu, 15 Apr 2010 14:22:06 +0000 Subject: [PATCH] Minor documentation improvements. --- .../Incomplete/BluetoothHost/BluetoothHost.c | 8 ++-- .../BluetoothHost/Lib/BluetoothACLPackets.c | 28 +++++++------- .../BluetoothHost/Lib/BluetoothHCICommands.c | 6 +-- .../BluetoothHost/Lib/BluetoothStack.c | 6 +-- LUFA/Common/Attributes.h | 10 +++-- LUFA/Doxygen.conf | 4 +- LUFA/License.txt | 17 +++++++++ LUFA/ManPages/Donating.txt | 2 +- LUFA/ManPages/LUFAvsAtmelStack.txt | 2 +- LUFA/ManPages/Licence.txt | 38 ------------------- LUFA/ManPages/LicenceInfo.txt | 20 ++++++++++ LUFA/ManPages/MainPage.txt | 4 +- LUFA/ManPages/SoftwareBootloaderJump.txt | 4 +- 13 files changed, 76 insertions(+), 73 deletions(-) create mode 100644 LUFA/License.txt delete mode 100644 LUFA/ManPages/Licence.txt create mode 100644 LUFA/ManPages/LicenceInfo.txt diff --git a/Demos/Host/Incomplete/BluetoothHost/BluetoothHost.c b/Demos/Host/Incomplete/BluetoothHost/BluetoothHost.c index 8dd5f91eb3..016b43ca33 100644 --- a/Demos/Host/Incomplete/BluetoothHost/BluetoothHost.c +++ b/Demos/Host/Incomplete/BluetoothHost/BluetoothHost.c @@ -199,7 +199,7 @@ void Bluetooth_Host_Task(void) /** Bluetooth stack callback event for a Bluetooth connection request. When this callback fires, the * user application must indicate if the connection is to be allowed or rejected. * - * \param RemoteAddress Bluetooth address of the remote device attempting the connection + * \param[in] RemoteAddress Bluetooth address of the remote device attempting the connection * * \return Boolean true to accept the connection, false to reject it */ @@ -241,9 +241,9 @@ void Bluetooth_DisconnectionComplete(void) /** Bluetooth stack callback event for a non-signal ACL packet reception. This callback fires once a connection * to a remote Bluetooth device has been made, and the remote device has sent a non-signalling ACL packet. * - * \param Data Pointer to a buffer where the received data is stored - * \param DataLen Length of the packet data, in bytes - * \param Channel Bluetooth ACL data channel information structure for the packet's destination channel + * \param[in] Data Pointer to a buffer where the received data is stored + * \param[in] DataLen Length of the packet data, in bytes + * \param[in] Channel Bluetooth ACL data channel information structure for the packet's destination channel */ void Bluetooth_PacketReceived(void* Data, uint16_t DataLen, Bluetooth_Channel_t* Channel) { diff --git a/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothACLPackets.c b/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothACLPackets.c index f96e10c37b..108abbf3d5 100644 --- a/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothACLPackets.c +++ b/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothACLPackets.c @@ -193,10 +193,10 @@ static void Bluetooth_ProcessIncommingACLPackets(void) /** Sends a packet to the remote device on the specified channel. * - * \param Data Pointer to a buffer where the data is to be sourced from - * \param DataLen Length of the data to send - * \param Channel Channel information structure containing the destination channel's information, NULL to send - * to the remote device's signalling channel + * \param[in] Data Pointer to a buffer where the data is to be sourced from + * \param[in] DataLen Length of the data to send + * \param[in] Channel Channel information structure containing the destination channel's information, NULL to send + * to the remote device's signalling channel * * \return A value from the \ref BT_SendPacket_ErrorCodes_t enum */ @@ -247,7 +247,7 @@ uint8_t Bluetooth_SendPacket(void* Data, uint16_t DataLen, Bluetooth_Channel_t* * repeatedly called. The returned channel is unusable by the user application until its State * element has progressed to the Open state. * - * \param PSM PSM of the service that the channel is to be opened for + * \param[in] PSM PSM of the service that the channel is to be opened for * * \return Pointer to the channel information structure of the opened channel, or NULL if no free channels */ @@ -311,7 +311,7 @@ Bluetooth_Channel_t* Bluetooth_OpenChannel(uint16_t PSM) * returned channel is unusable by the user application upon return however the channel is not completely * closed until its State element has progressed to the Closed state. * - * \param Channel Channel information structure of the channel to close + * \param[in,out] Channel Channel information structure of the channel to close */ void Bluetooth_CloseChannel(Bluetooth_Channel_t* Channel) { @@ -346,7 +346,7 @@ void Bluetooth_CloseChannel(Bluetooth_Channel_t* Channel) /** Internal Bluetooth stack Signal Command processing routine for a Connection Request command. * - * \param SignalCommandHeader Pointer to the start of the received packet's Signal Command header + * \param[in] SignalCommandHeader Pointer to the start of the received packet's Signal Command header */ static inline void Bluetooth_Signal_ConnectionReq(BT_Signal_Header_t* SignalCommandHeader) { @@ -419,7 +419,7 @@ static inline void Bluetooth_Signal_ConnectionReq(BT_Signal_Header_t* SignalComm /** Internal Bluetooth stack Signal Command processing routine for a Connection Response command. * - * \param SignalCommandHeader Pointer to the start of the received packet's Signal Command header + * \param[in] SignalCommandHeader Pointer to the start of the received packet's Signal Command header */ static inline void Bluetooth_Signal_ConnectionResp(BT_Signal_Header_t* SignalCommandHeader) { @@ -450,7 +450,7 @@ static inline void Bluetooth_Signal_ConnectionResp(BT_Signal_Header_t* SignalCom /** Internal Bluetooth stack Signal Command processing routine for a Configuration Request command. * - * \param SignalCommandHeader Pointer to the start of the received packet's Signal Command header + * \param[in] SignalCommandHeader Pointer to the start of the received packet's Signal Command header */ static inline void Bluetooth_Signal_ConfigurationReq(BT_Signal_Header_t* SignalCommandHeader) { @@ -537,7 +537,7 @@ static inline void Bluetooth_Signal_ConfigurationReq(BT_Signal_Header_t* SignalC /** Internal Bluetooth stack Signal Command processing routine for a Configuration Response command. * - * \param SignalCommandHeader Pointer to the start of the received packet's Signal Command header + * \param[in] SignalCommandHeader Pointer to the start of the received packet's Signal Command header */ static inline void Bluetooth_Signal_ConfigurationResp(BT_Signal_Header_t* SignalCommandHeader) { @@ -581,7 +581,7 @@ static inline void Bluetooth_Signal_ConfigurationResp(BT_Signal_Header_t* Signal /** Internal Bluetooth stack Signal Command processing routine for a Disconnection Request command. * - * \param SignalCommandHeader Pointer to the start of the received packet's Signal Command header + * \param[in] SignalCommandHeader Pointer to the start of the received packet's Signal Command header */ static inline void Bluetooth_Signal_DisconnectionReq(BT_Signal_Header_t* SignalCommandHeader) { @@ -627,7 +627,7 @@ static inline void Bluetooth_Signal_DisconnectionReq(BT_Signal_Header_t* SignalC /** Internal Bluetooth stack Signal Command processing routine for a Disconnection Response command. * - * \param SignalCommandHeader Pointer to the start of the received packet's Signal Command header + * \param[in] SignalCommandHeader Pointer to the start of the received packet's Signal Command header */ static inline void Bluetooth_Signal_DisconnectionResp(BT_Signal_Header_t* SignalCommandHeader) { @@ -652,7 +652,7 @@ static inline void Bluetooth_Signal_DisconnectionResp(BT_Signal_Header_t* Signal /** Internal Bluetooth stack Signal Command processing routine for an Echo Request command. * - * \param SignalCommandHeader Pointer to the start of the received packet's Signal Command header + * \param[in] SignalCommandHeader Pointer to the start of the received packet's Signal Command header */ static inline void Bluetooth_Signal_EchoReq(BT_Signal_Header_t* SignalCommandHeader) { @@ -678,7 +678,7 @@ static inline void Bluetooth_Signal_EchoReq(BT_Signal_Header_t* SignalCommandHea /** Internal Bluetooth stack Signal Command processing routine for an Information Request command. * - * \param SignalCommandHeader Pointer to the start of the received packet's Signal Command header + * \param[in] SignalCommandHeader Pointer to the start of the received packet's Signal Command header */ static inline void Bluetooth_Signal_InformationReq(BT_Signal_Header_t* SignalCommandHeader) { diff --git a/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothHCICommands.c b/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothHCICommands.c index d15439101e..2e5e4f7e39 100644 --- a/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothHCICommands.c +++ b/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothHCICommands.c @@ -311,9 +311,9 @@ void Bluetooth_HCITask(void) /** Sends a Bluetooth HCI control command to the attached Bluetooth device. * - * \param HCICommandHeader HCI command header to send to the attached device - * \param Parameters Pointer to the source of the control parameters (if any) - * \param ParameterLength Length of the parameters to send in bytes + * \param[in] HCICommandHeader HCI command header to send to the attached device + * \param[in] Parameters Pointer to the source of the control parameters (if any) + * \param[in] ParameterLength Length of the parameters to send in bytes * * \return A value from the USB_Host_SendControlErrorCodes_t enum. */ diff --git a/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothStack.c b/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothStack.c index d990ba02e8..3b0b61220c 100644 --- a/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothStack.c +++ b/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothStack.c @@ -67,9 +67,9 @@ void Bluetooth_Stack_USBTask(void) /** Retrieves the channel information structure with the given local or remote channel number from the channel list. * - * \param ChannelNumber Channel number to search for in the channel list - * \param SearchByRemoteChannel Indicated whether to search for a channel information structure by the given remote channel - * or local channel number + * \param[in] ChannelNumber Channel number to search for in the channel list + * \param[in] SearchByRemoteChannel Indicated whether to search for a channel information structure by the given remote channel + * or local channel number * * \return Pointer to the matching channel information structure in the channel table if found, NULL otherwise */ diff --git a/LUFA/Common/Attributes.h b/LUFA/Common/Attributes.h index 62d40734a6..fed511a50b 100644 --- a/LUFA/Common/Attributes.h +++ b/LUFA/Common/Attributes.h @@ -122,12 +122,16 @@ #endif /** Places the function in one of the initialization sections, which execute before the main function - * of the application. The init function number can be specified as "x", as an integer. Refer to the - * avr-libc manual for more information on the initialization sections. + * of the application. Refer to the avr-libc manual for more information on the initialization sections. + * + * \param[in] x Initialization section number where the function should be placed */ #define ATTR_INIT_SECTION(x) __attribute__ ((naked, section (".init" #x ))) - /** Marks a function as an alias for another function of name "x". */ + /** Marks a function as an alias for another function. + * + * \param[in] x Name of the function which the given function name should alias + */ #define ATTR_ALIAS(x) __attribute__ ((alias( #x ))) #endif diff --git a/LUFA/Doxygen.conf b/LUFA/Doxygen.conf index 2c7faf3b1e..ee8d9291f4 100644 --- a/LUFA/Doxygen.conf +++ b/LUFA/Doxygen.conf @@ -296,7 +296,7 @@ TYPEDEF_HIDES_STRUCT = YES # 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, # corresponding to a cache size of 2^16 = 65536 symbols -SYMBOL_CACHE_SIZE = 0 +SYMBOL_CACHE_SIZE = 1 #--------------------------------------------------------------------------- # Build related configuration options @@ -642,7 +642,7 @@ EXCLUDE_SYMBOLS = __* # directories that contain example code fragments that are included (see # the \include command). -EXAMPLE_PATH = +EXAMPLE_PATH = ../ # 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 diff --git a/LUFA/License.txt b/LUFA/License.txt new file mode 100644 index 0000000000..ea3b5d2dd1 --- /dev/null +++ b/LUFA/License.txt @@ -0,0 +1,17 @@ +Permission to use, copy, modify, and distribute this software +and its documentation for any purpose is hereby granted without +fee, provided that the above copyright notice appear in all +copies and that both that the copyright notice and this +permission notice and warranty disclaimer appear in supporting +documentation, and that the name of the author not be used in +advertising or publicity pertaining to distribution of the +software without specific, written prior permission. + +The author disclaim all warranties with regard to this +software, including all implied warranties of merchantability +and fitness. In no event shall the author be liable for any +special, indirect or consequential damages or any damages +whatsoever resulting from loss of use, data or profits, whether +in an action of contract, negligence or other tortious action, +arising out of or in connection with the use or performance of +this software. diff --git a/LUFA/ManPages/Donating.txt b/LUFA/ManPages/Donating.txt index a09707820f..ed778eaf2a 100644 --- a/LUFA/ManPages/Donating.txt +++ b/LUFA/ManPages/Donating.txt @@ -15,7 +15,7 @@ * donations are greatly appreciated. * * Note that commercial entities can remove the attribution portion of the LUFA licence by a one-time fee - see - * \ref Page_Licence for more details (Note: Please do NOT pay this in advance through the donation link below - + * \ref Page_LicenceInfo for more details (Note: Please do NOT pay this in advance through the donation link below - * contact author for payment details.). * * \image html "http://www.pledgie.com/campaigns/6927.png?skin_name=chrome" diff --git a/LUFA/ManPages/LUFAvsAtmelStack.txt b/LUFA/ManPages/LUFAvsAtmelStack.txt index 89d85c1085..8f39b72397 100644 --- a/LUFA/ManPages/LUFAvsAtmelStack.txt +++ b/LUFA/ManPages/LUFAvsAtmelStack.txt @@ -12,7 +12,7 @@ * official Atmel USB stack. Below are just some of the advantages to choosing LUFA over the official stack. * * - Licensing: - * LUFA is released under a very permissive MIT license (see \ref Page_Licence), while the Atmel stack carries several + * LUFA is released under a very permissive MIT license (see \ref Page_LicenceInfo), while the Atmel stack carries several * restrictions as to how and where it can be used. LUFA's licensing should be suitable for both Commercial and Non-Commercial * entities alike. * diff --git a/LUFA/ManPages/Licence.txt b/LUFA/ManPages/Licence.txt deleted file mode 100644 index 2160d7960c..0000000000 --- a/LUFA/ManPages/Licence.txt +++ /dev/null @@ -1,38 +0,0 @@ -/** \file - * - * This file contains special DoxyGen information for the generation of the main page and other special - * documentation pages. It is not a project source file. - */ - -/** - * \page Page_Licence Source Code Licence - * - * The LUFA library is currently released under the MIT licence, included below. - * - * Commercial entities can opt out of the public disclosure clause in this license - * for a one-time US$1500 payment. This provides a non-exclusive modified MIT licensed which - * allows for the free use of the LUFA library, bootloaders and (where the sole copyright - * is attributed to Dean Camera) demos without public disclosure within an organisation, in - * addition to three free hours of consultation with the library author, and priority support. - * Please contact the author for more information via the address shown on on \ref Page_Resources. - * - * \verbatim - * Permission to use, copy, modify, and distribute this software - * and its documentation for any purpose is hereby granted without - * fee, provided that the above copyright notice appear in all - * copies and that both that the copyright notice and this - * permission notice and warranty disclaimer appear in supporting - * documentation, and that the name of the author not be used in - * advertising or publicity pertaining to distribution of the - * software without specific, written prior permission. - * - * The author disclaim all warranties with regard to this - * software, including all implied warranties of merchantability - * and fitness. In no event shall the author be liable for any - * special, indirect or consequential damages or any damages - * whatsoever resulting from loss of use, data or profits, whether - * in an action of contract, negligence or other tortious action, - * arising out of or in connection with the use or performance of - * this software. - * \endverbatim - */ diff --git a/LUFA/ManPages/LicenceInfo.txt b/LUFA/ManPages/LicenceInfo.txt new file mode 100644 index 0000000000..f105db7dc0 --- /dev/null +++ b/LUFA/ManPages/LicenceInfo.txt @@ -0,0 +1,20 @@ +/** \file + * + * This file contains special DoxyGen information for the generation of the main page and other special + * documentation pages. It is not a project source file. + */ + +/** + * \page Page_LicenceInfo Source Code Licence + * + * The LUFA library is currently released under the MIT licence, included below. + * + * Commercial entities can opt out of the public disclosure clause in this license + * for a one-time US$1500 payment. This provides a non-exclusive modified MIT licensed which + * allows for the free use of the LUFA library, bootloaders and (where the sole copyright + * is attributed to Dean Camera) demos without public disclosure within an organisation, in + * addition to three free hours of consultation with the library author, and priority support. + * Please contact the author for more information via the address shown on on \ref Page_Resources. + * + * \verbinclude License.txt + */ diff --git a/LUFA/ManPages/MainPage.txt b/LUFA/ManPages/MainPage.txt index 6bf7727281..521b30ba69 100644 --- a/LUFA/ManPages/MainPage.txt +++ b/LUFA/ManPages/MainPage.txt @@ -13,7 +13,7 @@ * * LUFA is donationware. For author and donation information, see \ref Page_Donating. * - * LUFA is an open-source USB library for the USB-enabled AVR microcontrollers, released under the MIT license (see \ref Page_Licence). + * LUFA is an open-source USB library for the USB-enabled AVR microcontrollers, released under the MIT license (see \ref Page_LicenceInfo). * It supports a large number of USB AVR models and boards (see \ref Page_DeviceSupport). It is designed to provide an easy to use, * feature rich framework for the development of USB peripherals and hosts. * @@ -37,7 +37,7 @@ * - \subpage Page_WhyUseLUFA What are the advantages of using LUFA? * - \subpage Page_LUFAvsAtmelStack How does LUFA compare to the Atmel USB AVR stack? * - \subpage Page_AlternativeStacks Alternative USB AVR Stacks - * - \subpage Page_Licence Project source licence and commercial use information + * - \subpage Page_LicenceInfo Project source licence and commercial use information * - \subpage Page_Donating Donating to support this project * - \subpage Page_LibraryApps Overview of included Demos, Bootloaders and Projects */ diff --git a/LUFA/ManPages/SoftwareBootloaderJump.txt b/LUFA/ManPages/SoftwareBootloaderJump.txt index afdc0b32a8..82fce4a6d5 100644 --- a/LUFA/ManPages/SoftwareBootloaderJump.txt +++ b/LUFA/ManPages/SoftwareBootloaderJump.txt @@ -31,8 +31,8 @@ * #define MAGIC_BOOT_KEY 0xDC42ACCA * #define BOOTLOADER_START_ADDRESS ({FLASH_SIZE_BYTES} - {BOOTLOADER_SEC_SIZE_BYTES}) * - * int Bootloader_Jump_Check(void) ATTR_INIT_SECTION(3); - * int Bootloader_Jump_Check(void) + * void Bootloader_Jump_Check(void) ATTR_INIT_SECTION(3); + * void Bootloader_Jump_Check(void) * { * // If the bootloader key is correct, clear it and jump to the bootloader * if (Boot_Key == MAGIC_BOOT_KEY)