From c939c1124806698b756ebc37a4f0d61f16bf3252 Mon Sep 17 00:00:00 2001 From: hathach Date: Mon, 31 Mar 2014 16:07:04 +0700 Subject: [PATCH] document --- tinyusb.Doxyfile | 4 +-- tinyusb/doxygen/coding_standard.md | 52 +++++++++++++++++++++--------- tinyusb/doxygen/get_started.md | 4 ++- 3 files changed, 42 insertions(+), 18 deletions(-) diff --git a/tinyusb.Doxyfile b/tinyusb.Doxyfile index c0cbd1b4..9180ca17 100644 --- a/tinyusb.Doxyfile +++ b/tinyusb.Doxyfile @@ -58,7 +58,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = docs +OUTPUT_DIRECTORY = ../../web/gh_page # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and @@ -1079,7 +1079,7 @@ GENERATE_HTML = YES # The default directory is: html. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_OUTPUT = html +HTML_OUTPUT = 0.4 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each # generated HTML page (for example: .htm, .php, .asp). diff --git a/tinyusb/doxygen/coding_standard.md b/tinyusb/doxygen/coding_standard.md index 3a3ad8b3..3eb3c0d7 100644 --- a/tinyusb/doxygen/coding_standard.md +++ b/tinyusb/doxygen/coding_standard.md @@ -12,10 +12,22 @@ Where is possible, standards are followed but it is almost impossible to follow MISRA-C is well respected & a bar for industrial coding standard. -- **Rule 2.2: use only /\*** It has long passed the day that C99 comment style // will cause any issues, especially compiler's C99 mode is required to build tinyusb. -- **Rule 8.5: No definitions of objects or function in a header file** function definitions in header files are used to allow 'inlining' -- **Rule 14.7: A function shall have a single point of exit at the end of the function** Unfortunately, following this rule will have a lot of nesting if-else, I prefer to exit as soon as possible with assert style and flatten if-else. -- **Rule 18.4: Unions shall not be used** sorry MISRA, union is required to effectively mapped to MCU's registers +- **Rule 2.2: use only** + + It has long passed the day that C99 comment style // will cause any issues, especially compiler's C99 mode is required to build tinyusb. + +- **Rule 8.5: No definitions of objects or function in a header file** + + function definitions in header files are used to allow 'inlining' + +- **Rule 14.7: A function shall have a single point of exit at the end of the function** + + Unfortunately, following this rule will have a lot of nesting if-else, I prefer to exit as soon as possible with assert style and flatten if-else. + +- **Rule 18.4: Unions shall not be used** + + sorry MISRA, union is required to effectively mapped to MCU's registers + - expect to have more & more exceptions. ## Power of 10 ## @@ -23,35 +35,45 @@ MISRA-C is well respected & a bar for industrial coding standard. is a small & easy to remember but yet powerful coding guideline. Most (if not all) of the rules here are included in JPL. Because it is very small, all the rules will be listed here, those with *italic* are compliant, **bold** are violated. 1. *Restrict to simple control flow constructs* -yes, I hate goto statement, therefore there is none of those here + + yes, I hate goto statement, therefore there is none of those here 2. *Give all loops a fixed upper-bound* -one of my favorite rule + + one of my favorite rule 3. *Do not use dynamic memory allocation after initialization* -the tinyusb uses the static memory for all of its data. + + the tinyusb uses the static memory for all of its data. 4. **Limit functions to no more than 60 lines of text** -60 is a little bit too strict, I will update the relaxing number later + + 60 is a little bit too strict, I will update the relaxing number later 5. *Use minimally two assertions per function on average* -not sure the exact number, but I use a tons of those assert + + not sure the exact number, but I use a tons of those assert 6. *Declare data objects at the smallest possible level of scope* -one of the best & easiest rule to follow + + one of the best & easiest rule to follow 7. *Check the return value of non-void functions, and check the validity of function parameters* -I did check all of the public application API's parameters. For internal API, calling function needs to trust their caller to reduce duplicated check. + + I did check all of the public application API's parameters. For internal API, calling function needs to trust their caller to reduce duplicated check. 8. **Limit the use of the preprocessor to file inclusion and simple macros** -Although I prefer inline function, however C macros are far powerful than that. I simply cannot hold myself to use, for example X-Macro technique to simplify code. + + Although I prefer inline function, however C macros are far powerful than that. I simply cannot hold myself to use, for example X-Macro technique to simplify code. 9. *Limit the use of pointers. Use no more than two levels of dereferencing per expression* -never intend to get in trouble with complex pointer dereferencing. + + never intend to get in trouble with complex pointer dereferencing. 10. *Compile with all warnings enabled, and use one or more source code analyzers* -I try to use all the defensive options of gnu, let me know if I miss some. ->-Wextra -Wswitch-default -Wunsafe-loop-optimizations -Wcast-align -Wlogical-op -Wpacked-bitfield-compat -Wnested-externs -Wredundant-decls -Winline + + I try to use all the defensive options of gnu, let me know if I miss some. + >-Wextra -Wswitch-default -Wunsafe-loop-optimizations -Wcast-align -Wlogical-op -Wpacked-bitfield-compat -Wnested-externs -Wredundant-decls -Winline ## JPL ## diff --git a/tinyusb/doxygen/get_started.md b/tinyusb/doxygen/get_started.md index 9af71da4..ae5d666a 100644 --- a/tinyusb/doxygen/get_started.md +++ b/tinyusb/doxygen/get_started.md @@ -90,4 +90,6 @@ Application demo is written to have the code excluded if its required option is In addition, there are some configuration you can change such as - CFG_UART_BAUDRATE in board.h -- CFG_PRINTF_TARGET in the specific board header (e.g board_ea4357.h) to either Semihost, Uart, or SWO. \ No newline at end of file +- CFG_PRINTF_TARGET in the specific board header (e.g board_ea4357.h) to either Semihost, Uart, or SWO. + +\subpage md_boards_readme \ No newline at end of file