X-Git-Url: https://sigrok.org/gitweb/?p=libsigrokdecode.git;a=blobdiff_plain;f=HACKING;h=6aaedac13acb0939feda256ef4e35e5ccba31736;hp=82176e14c216b295d0e7cc46da250ce21ec410bb;hb=991c44f33a55733610f6d9da1efbcc5bf1074dee;hpb=f11e9498c83d4b27ffc1029f6dbd7ef871953aca diff --git a/HACKING b/HACKING index 82176e1..6aaedac 100644 --- a/HACKING +++ b/HACKING @@ -32,18 +32,27 @@ Contributions Random notes ------------ - - Consistently use g_try_malloc() / g_try_malloc0(). Do not use standard + - Don't do variable declarations in compound statements, only at the + beginning of a function. + + - Generally avoid assigning values to variables at declaration time, + especially so for complex and/or run-time dependent values. + + - Consistently use g_*malloc() / g_*malloc0(). Do not use standard malloc()/calloc() if it can be avoided (sometimes other libs such as libftdi can return malloc()'d memory, for example). - Always properly match allocations with the proper *free() functions. If - glib's g_try_malloc()/g_try_malloc0() was used, use g_free() to free the + glib's g_*malloc()/g_*malloc0() was used, use g_free() to free the memory. Otherwise use standard free(). Never use the wrong function! - - Never use g_malloc() or g_malloc0(). These functions do not return NULL - if not enough memory is available but rather lead to an exit() or segfault - instead. This behaviour is not acceptable for libraries. - Use g_try_malloc()/g_try_malloc0() instead and check the return value. + - We assume that "small" memory allocations (< 1MB) will always succeed. + Thus, it's fine to use g_malloc() or g_malloc0() for allocations of + simple/small structs and such (instead of using g_try_malloc()), and + there's no need to check the return value. + + Do use g_try_malloc() or g_try_malloc0() for large (>= 1MB) allocations + and check the return value. - You should never print any messages (neither to stdout nor stderr nor elsewhere) "manually" via e.g. printf() or g_log() or similar functions. @@ -56,7 +65,7 @@ Random notes - Consistently use the same naming convention for #include guards in headers: __ This ensures that all #include guards are always unique and consistent. - Example: LIBSIGROKDECODE_SIGROKDECODE_INTERNAL_H + Example: LIBSIGROKDECODE_LIBSIGROKDECODE_INTERNAL_H - Consistently use the same naming convention for API functions: __(). @@ -74,6 +83,18 @@ Random notes should end with "_all", e.g. "_remove_all", "_get_all", and so on. Use "_remove_all" in favor of "_clear" for consistency. + - All enums should generally use an explicit start number of 10000. + If there are multiple "categories" in the enum entries, each category + should be 10000 entries apart from the next one. The start of categories + are thus 10000, 20000, 30000, and so on. + + Adding items to an enum MUST always append to a "category", never add + items in the middle of a category. The order of items MUST NOT be changed. + Any of the above would break the ABI. + + The enum item 0 is special and is used as terminator in some lists, thus + enums should not use this for "valid" entries (and start at 10000 instead). + Doxygen ------- @@ -91,8 +112,13 @@ Doxygen Variables that are "static" don't need to be marked like this. - Mark all public API functions (SRD_API) with a @since tag which indicates - in which release the respective function was added. If the function has - existed before, but its API changed later, document this as well. + in which release the respective function was added (e.g. "@since 0.1.0"). + + If the function has existed before, but its API changed later, the @since + tag should mention only the release when the API last changed. + + Example: The srd_foo() call was added in 0.1.0, but the API changed in + the later 0.2.0 release. The docs should read "@since 0.2.0" in that case. Non-public functions (static ones, and those marked SRD_PRIV) don't need to have @since markers. @@ -100,12 +126,6 @@ Doxygen The @since tag should be the last one, i.e. it should come after @param, @return, @see, and so on. - Examples: - - @since 0.1.0 - - @since 0.1.1 (but the API changed in 0.2.0) - Protocol decoder guidelines --------------------------- @@ -154,6 +174,21 @@ Protocol decoder guidelines 'FIND_ADDRESS', 'Get Temperature', 'start' +Testsuite +--------- + +You can run the libsigrokdecode testsuite using: + + $ make check + + +Protocol decoder test framework +------------------------------- + +Please see the sigrok-test repository for a protocol decoder test suite that +checks the decoded data of various PDs against known-good reference data. + + Release engineering -------------------