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.
- Consistently use the same naming convention for #include guards in headers:
<PROJECTNAME>_<PATH_TO_FILE>_<FILE>
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:
<libprefix>_<groupname>_<action>().
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
-------
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.
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
---------------------------
'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
-------------------
projects / libsigrokdecode.git / blobdiff