From 0672779d5e3e128ef3f7ec932772ff6d65fcbc50 Mon Sep 17 00:00:00 2001 From: Uwe Hermann Date: Sun, 4 May 2014 21:59:57 +0200 Subject: [PATCH] HACKING: Update to current conventions. (mostly copied from libsigrok, which normally has the same conventions) --- HACKING | 51 ++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 42 insertions(+), 9 deletions(-) diff --git a/HACKING b/HACKING index 82176e1..a9a6a03 100644 --- a/HACKING +++ b/HACKING @@ -32,6 +32,12 @@ Contributions Random notes ------------ + - 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_try_malloc() / g_try_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). @@ -56,7 +62,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 +80,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 +109,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 +123,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 +171,22 @@ Protocol decoder guidelines 'FIND_ADDRESS', 'Get Temperature', 'start' +Testsuite +--------- + +You can run the libsigrokdecode testsuite using: + + $ make check + + +Protocol decoder test framework +------------------------------- + +You can run the protocol decoder tests using (e.g.): + + $ ./tests/pdtest -r -a -v + + Release engineering ------------------- -- 2.30.2