X-Git-Url: https://sigrok.org/gitweb/?p=libsigrokdecode.git;a=blobdiff_plain;f=HACKING;h=a9a6a03f1d70d82df6b6960765b2a19ec3a13771;hp=922415faac884416ebeb7756fcf632c49f9ea2dc;hb=1f6f2ad8c33e58cfd40ea0370e6d2dfbd6040026;hpb=1859c4804d04b58ba15a316eb16035c6bbb611fe;ds=sidebyside

diff --git a/HACKING b/HACKING
index 922415f..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:
    <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>().
@@ -74,10 +80,49 @@ 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
+-------
+
  - In Doxygen comments, put an empty line between the block of @param lines
    and the final @return line. The @param lines themselves (if there is more
    than one) are not separated by empty lines.
 
+ - Mark private functions (SRD_PRIV) with /** @private */, so that Doxygen
+   doesn't include them in the output. Functions that are "static" anyway
+   don't need to be marked like this.
+
+ - Mark private variables/#defines with /** @cond PRIVATE */ and
+   /** @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 (SRD_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 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.
+
 
 Protocol decoder guidelines
 ---------------------------
@@ -126,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
 -------------------