X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=HACKING;h=0e818c2116d718c0703e1dceda4ecd06ed333e10;hb=390795c0999ae3a41b97f9a8e2c154c81e6d064e;hp=9c422a328bce348a1832b9223ea838a85d94cb4d;hpb=2bba3dd3a836f4a6d497709d321557a48e6425a3;p=libsigrok.git diff --git a/HACKING b/HACKING index 9c422a32..0e818c21 100644 --- a/HACKING +++ b/HACKING @@ -45,7 +45,11 @@ You can apply it like this: $ cd libsigrok $ git am 0001-tondaj-sl-814-Initial-driver-skeleton.patch -You can now edit the files in the hardware/tondaj-sl-814 directory as needed. +You can now edit the files in the hardware/tondaj-sl-814 directory as needed +and implement your driver based on the skeleton files there. That means your +patch submission later will consist of at least two patches: the initial one +adding the skeleton driver, and one or more additional patches that actually +implement the respective driver code. The manual way: @@ -71,6 +75,12 @@ See existing drivers or the 'new-driver' output for the details. 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). @@ -95,7 +105,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. - Examples: LIBSIGROK_LIBSIGROK_H, LIBSIGROK_HARDWARE_ASIX_SIGMA_ASIX_SIGMA_H + Examples: LIBSIGROK_LIBSIGROK_H, LIBSIGROK_HARDWARE_MIC_985XX_PROTOCOL_H - Consistently use the same naming convention for API functions: __(). @@ -115,6 +125,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 ------- @@ -131,6 +153,29 @@ Doxygen /** @endcond */, so that Doxygen doesn't include them in the output. Variables that are "static" don't need to be marked like this. + - Mark all public API functions (SR_API) with a @since tag which indicates + 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 sr_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 SR_PRIV) don't need + to have @since markers. + + The @since tag should be the last one, i.e. it should come after @param, + @return, @see, and so on. + + +Testsuite +--------- + +You can run the libsigrok testsuite using: + + $ make check + Release engineering -------------------