From 48b3c9976c76258e99166023db241ca4261f679f Mon Sep 17 00:00:00 2001 From: Dean Camera Date: Mon, 15 Jun 2009 11:01:58 +0000 Subject: [PATCH] Use sub pages in main library documentation to improve readability. --- LUFA.pnproj | 2 +- LUFA/AboutLUFA.txt | 20 +++++++++ LUFA/ChangeLog.txt | 4 +- LUFA/CompileTimeTokens.txt | 2 +- LUFA/DevelopingWithLUFA | 17 ++++++++ LUFA/DevelopingWithLUFA.txt | 21 ++++++++++ LUFA/DeviceSupport.txt | 29 +++++++++++++ LUFA/Donating.txt | 17 ++++++++ LUFA/Doxygen.conf | 2 +- LUFA/LibraryResources.txt | 21 ++++++++++ LUFA/License.txt | 37 +++++++++++++++++ LUFA/MainPage.txt | 83 ++++--------------------------------- README.txt | 22 ++++++++++ makefile | 5 ++- 14 files changed, 199 insertions(+), 83 deletions(-) create mode 100644 LUFA/AboutLUFA.txt create mode 100644 LUFA/DevelopingWithLUFA create mode 100644 LUFA/DevelopingWithLUFA.txt create mode 100644 LUFA/DeviceSupport.txt create mode 100644 LUFA/Donating.txt create mode 100644 LUFA/LibraryResources.txt create mode 100644 LUFA/License.txt create mode 100644 README.txt diff --git a/LUFA.pnproj b/LUFA.pnproj index d40eea7d99..5ff8073d3d 100644 --- a/LUFA.pnproj +++ b/LUFA.pnproj @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/LUFA/AboutLUFA.txt b/LUFA/AboutLUFA.txt new file mode 100644 index 0000000000..78900d369b --- /dev/null +++ b/LUFA/AboutLUFA.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_AboutLUFA About LUFA + * + * This section of the manual contains information about the library as a whole, including its supported targets, + * past and planned changes, and links to other projects incorporating LUFA. + * + * Subsections: + * - \subpage Page_DeviceSupport Current Device and Hardware Support + * - \subpage Page_Resources LUFA and USB Related Resources + * - \subpage Page_ChangeLog Project Changelog + * - \subpage Page_FutureChanges Planned Changes to the Library + * - \subpage Page_LUFAPoweredProjects Other Projects Using LUFA + */ + \ No newline at end of file diff --git a/LUFA/ChangeLog.txt b/LUFA/ChangeLog.txt index 17f652e201..1047d4933e 100644 --- a/LUFA/ChangeLog.txt +++ b/LUFA/ChangeLog.txt @@ -12,8 +12,8 @@ * - Added new class drivers and matching demos to the library for rapid application development * - Added incomplete device and host mode demos for later enhancement * - Changed bootloaders to use FLASHEND rather than the existence of RAMPZ to determine if far FLASH pointers are needed - * - Error status LEDs shown when device endpoint configuration fails to complete - * - MIDI device demo no longer blocks if a note change event is sent while the endpoint is not ready + * - Error status LEDs shown when device endpoint configuration fails to complete in all demos and projects + * - Low level API MIDI device demo no longer blocks if a note change event is sent while the endpoint is not ready * - Fixes to MassStorageHost for better device compatibility (increase command timeout, change MassStore_WaitForDataReceived() * to only unfreeze and check one data pipe at a time) * - Internal per-device preprocessing conditions changed to per-device series rather than per controller group for finer-grain diff --git a/LUFA/CompileTimeTokens.txt b/LUFA/CompileTimeTokens.txt index dcb5816de5..d8a7cf74a7 100644 --- a/LUFA/CompileTimeTokens.txt +++ b/LUFA/CompileTimeTokens.txt @@ -4,7 +4,7 @@ * documentation pages. It is not a project source file. */ -/** \page TokenSummary Summary of Compile Tokens +/** \page Page_TokenSummary Summary of Compile Tokens * * The following lists all the possible tokens which can be defined in a project makefile, and passed to the * compiler via the -D switch, to alter the LUFA library code. These tokens may alter the library behaviour, diff --git a/LUFA/DevelopingWithLUFA b/LUFA/DevelopingWithLUFA new file mode 100644 index 0000000000..519b96c58c --- /dev/null +++ b/LUFA/DevelopingWithLUFA @@ -0,0 +1,17 @@ +/** \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_DevelopingWithLUFA Developing With LUFA + * + * \subpage Page_BuildLibrary + * \subpage Page_TokenSummary + * \subpage Page_GettingStarted + * \subpage Page_Migration + * \subpage Page_VIDPID + * \subpage Page_WritingBoardDrivers + */ + \ No newline at end of file diff --git a/LUFA/DevelopingWithLUFA.txt b/LUFA/DevelopingWithLUFA.txt new file mode 100644 index 0000000000..8c708af28f --- /dev/null +++ b/LUFA/DevelopingWithLUFA.txt @@ -0,0 +1,21 @@ +/** \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_DevelopingWithLUFA Developing With LUFA + * + * This section of the manual contains information on LUFA development, such as Getting Started information, + * information on compile-time tuning of the library and other developer-related sections. + * + * Subsections: + * - \subpage Page_GettingStarted Getting Started + * - \subpage Page_TokenSummary Summary of Compile Time Tokens + * - \subpage Page_Migration Migrating from an Older LUFA Version + * - \subpage Page_VIDPID Allocated USB VID and PID Values + * - \subpage Page_BuildLibrary Building as a Linkable Library + * - \subpage Page_WritingBoardDrivers How to Write Custom Board Drivers + */ + \ No newline at end of file diff --git a/LUFA/DeviceSupport.txt b/LUFA/DeviceSupport.txt new file mode 100644 index 0000000000..1d06d52ee1 --- /dev/null +++ b/LUFA/DeviceSupport.txt @@ -0,0 +1,29 @@ +/** \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_DeviceSupport Device and Hardware Support + * + * Currently supported AVR models: + * - AT90USB1286 (USB Device Only) + * - AT90USB1287 (USB Host and Device) + * - AT90USB646 (USB Device Only) + * - AT90USB647 (USB Host and Device) + * - AT90USB82 (USB Device Only) + * - AT90USB162 (USB Device Only) + * - ATMEGA16U4 (USB Device Only) + * - ATMEGA32U4 (USB Device Only) + * - ATMEGA32U6 (USB Device Only) + * + * Currently supported Atmel boards: + * - AT90USBKEY + * - STK525 + * - STK526 + * - RZUSBSTICK + * - ATAVRUSBRF01 + * - Custom User Boards + */ + \ No newline at end of file diff --git a/LUFA/Donating.txt b/LUFA/Donating.txt new file mode 100644 index 0000000000..34c25c62d5 --- /dev/null +++ b/LUFA/Donating.txt @@ -0,0 +1,17 @@ +/** \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_Donating Donating to Support This Project + * + * I am a 20 year old University student studying for a double degree in Computer Science and Electronics Engineering. + * The development and support of this library requires much effort from myself, as I am the sole developer, maintainer + * and supporter. Please consider donating a small amount to support this and my future Open Source projects - All + * donations are greatly appreciated. + * + * Donate to this project at http://www.fourwalledcubicle.com via PayPal - Thanks in Advance! + */ + \ No newline at end of file diff --git a/LUFA/Doxygen.conf b/LUFA/Doxygen.conf index 440031393d..6422c213ec 100644 --- a/LUFA/Doxygen.conf +++ b/LUFA/Doxygen.conf @@ -25,7 +25,7 @@ DOXYFILE_ENCODING = UTF-8 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded # by quotes) that should identify the project. -PROJECT_NAME = "LUFA Library" +PROJECT_NAME = "LUFA (Formerly MyUSB) Library" # The PROJECT_NUMBER tag can be used to enter a project or revision number. # This could be handy for archiving the generated documentation or diff --git a/LUFA/LibraryResources.txt b/LUFA/LibraryResources.txt new file mode 100644 index 0000000000..a1005d4013 --- /dev/null +++ b/LUFA/LibraryResources.txt @@ -0,0 +1,21 @@ +/** \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_Resources Library Resources + * + * Project Homepage: http://www.fourwalledcubicle.com/LUFA.php \n + * Development Blog: http://www.fourwalledcubicle.com/blog \n + * Discussion Group: http://groups.google.com/group/myusb-support-list \n + * SVN Access, Bug Reports and Feature Requests: http://code.google.com/p/lufa-lib/ \n + * Author's Website: http://www.fourwalledcubicle.com \n + * + * WinAVR Website: http://winavr.sourceforge.net \n + * avr-libc Website: http://www.nongnu.org/avr-libc/ \n + * + * USB-IF Website: http://www.usb.org \n + */ + \ No newline at end of file diff --git a/LUFA/License.txt b/LUFA/License.txt new file mode 100644 index 0000000000..293c18bdbe --- /dev/null +++ b/LUFA/License.txt @@ -0,0 +1,37 @@ +/** \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 License + * + * 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. Please + * contact the author for more information. + * + * \verbatim + * Permission to use, copy, modify, and distribute this software + * and its documentation for any purpose and without fee is hereby + * granted, 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/MainPage.txt b/LUFA/MainPage.txt index 2ff8b0c650..b326f5cd59 100644 --- a/LUFA/MainPage.txt +++ b/LUFA/MainPage.txt @@ -5,33 +5,12 @@ */ /** - * \mainpage About the LUFA (Formerly MyUSB) Library + * \mainpage General Information * - * Lightweight USB Framework for AVRs Library, written by Dean Camera. + * Lightweight USB Framework for AVRs Library, written by Dean Camera. * - * \section Sec_About About this library - * - * Originally based on the AT90USBKEY from Atmel, it is an open-source, driver for the USB-enabled AVR - * microcontrollers, released under the MIT license. - * - * Currently supported AVR models: - * - AT90USB1286 (USB Device Only) - * - AT90USB1287 (USB Host and Device) - * - AT90USB646 (USB Device Only) - * - AT90USB647 (USB Host and Device) - * - AT90USB82 (USB Device Only) - * - AT90USB162 (USB Device Only) - * - ATMEGA16U4 (USB Device Only) - * - ATMEGA32U4 (USB Device Only) - * - ATMEGA32U6 (USB Device Only) - * - * Currently supported Atmel boards: - * - AT90USBKEY - * - STK525 - * - STK526 - * - RZUSBSTICK - * - ATAVRUSBRF01 - * - Custom User Boards + * Originally based on the AT90USBKEY from Atmel, it is an open-source USB library for the USB-enabled AVR + * microcontrollers, released under the MIT license. It now supports a large number of USB AVR models and boards. * * The library is currently in a stable release, suitable for download and incorporation into user projects for * both host and device modes. For information about the project progression, check out my blog. @@ -40,50 +19,6 @@ * library API more streamlined and robust. You can download AVR-GCC for free in a convenient windows package, * from the the WinAVR website. * - * - * \section Sec_Links Library Links - * Project Homepage: http://www.fourwalledcubicle.com/LUFA.php \n - * Development Blog: http://www.fourwalledcubicle.com/blog \n - * Discussion Group: http://groups.google.com/group/myusb-support-list \n - * SVN Access, Bug Reports and Feature Requests: http://code.google.com/p/lufa-lib/ \n - * Author's Website: http://www.fourwalledcubicle.com \n - * - * WinAVR Website: http://winavr.sourceforge.net \n - * avr-libc Website: http://www.nongnu.org/avr-libc/ \n - * - * USB-IF Website: http://www.usb.org \n - * - * - * \section Sec_License License - * 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. Please - * contact the author for more information. - * - * \verbatim - * Permission to use, copy, modify, and distribute this software - * and its documentation for any purpose and without fee is hereby - * granted, 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 - * - * * \section Sec_Demos Demos and Bootloaders * The LUFA library ships with several different host and device demos, located in the /Demos/ subdirectory. * If this directory is missing, please re-download the project from the project homepage. @@ -93,11 +28,7 @@ * CDC class (AVR109 protocol) is compatible with such open source software as AVRDUDE and AVR-OSP, and the TeensyLoader * HID class bootloader is compatible with the software from PJRC (http://www.pjrc.com/teensy/index.html). * - * - * \section Sec_Donations Donate - * I am a 20 year old University student studying for a double degree in Computer Science and Electronics Engineering. - * The development and support of this library requires much effort from myself. Please consider donating a small amount - * to myself to support this and my future Open Source projects. You can donate any amount via PayPal on my website, - * http://www.fourwalledcubicle.com . All donations are greatly appreciated. + * Subsections: + * - \subpage Page_Licence Project License + * - \subpage Page_Donating Donating to Support this Project */ - diff --git a/README.txt b/README.txt new file mode 100644 index 0000000000..36c68a43a8 --- /dev/null +++ b/README.txt @@ -0,0 +1,22 @@ + + _ _ _ ___ _ + | | | | | __/ \ + | |_| U | _| o | - The Lightweight USB + |___|___|_||_n_| Framework for AVRs + ========================================= + Written by Dean Camera + http://www.fourwalledcubicle.com + ========================================= + + +This package contains the complete LUFA library, demos, user-submitted projects +and bootloaders for use with compatible microcontroller models. To get started, +you will need to install the "Doxygen" documentation generation tool from +www.doxygen.org, and run "make doxygen" from the command line. From there, the +generated HTML documentation for the library itself will be avaliable in the +LUFA/Documentation/html/ directory. View this documentation in your chosen web +browser for further Getting Started information. + +The documentation for the library itself (but not the documentation for the +individual demos, projects or bootloaders) is also available as a seperate +package from the project webpage for convenience if Doxygen cannot be installed. \ No newline at end of file diff --git a/makefile b/makefile index 6fca4a6b7c..5446c939d4 100644 --- a/makefile +++ b/makefile @@ -9,8 +9,9 @@ # Makefile to build the LUFA library and Demos. # Call with "make all" to rebuild everything, "make clean" to clean everything, -# "make clean_list" to remove all intermediatary files but preserve any binaries -# and "make doxygen" to document the project with DoxyGen (if installed). +# "make clean_list" to remove all intermediatary files but preserve any binaries, +# "make doxygen" to document the library/demos/etc. with DoxyGen (if installed) and +# "make clean_doxygen" to remove generated Doxygen documentation. # It is suggested that for the master build, the --quiet switch is passed to make, # to remove all the commands from the output. This gives a much easier to read