HACKING: Minor updates.

[libsigrok.git] / HACKING

diff --git a/HACKING b/HACKING
index cf407c985d95fa3c4b8ef0992a8da1a7af99d39a..2b4be7eaefa8c2efe6d993a73fbacfe6315118d5 100644 (file)
--- 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 src/hardware/tondaj-sl-814 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:
@@ -55,15 +59,10 @@ This is a rough overview of what you need to do in order to add a new driver
 (using the Tondaj SL-814 device as example). It's basically what the
 'new-driver' script (see above) does for you:
 
- - configure.ac:
-   - Add an --enable-tondaj-sl-814 option.
-   - Add "hardware/tondaj-sl-814/Makefile" to the AC_CONFIG_FILES list.
-   - Add and entry for the device in the "Enabled hardware drivers" list
-     at the bottom of the file.
- - hardware/Makefile.am: Add "tondaj-sl-814" to the SUBDIRS variable.
- - hwdriver.c: Add a tondaj_sl_814_driver_info entry in two places.
- - hardware/tondaj-sl-814/ directory: Add the following files:
-   Makefile.am, api.c, protocol.c, protocol.h
+ - Makefile.am: Add HW_TONDAJ_SL_814 and add to libsigrok_la_SOURCES.
+ - configure.ac: Add a DRIVER() and DRIVER2() call.
+ - src/drivers.c: Add a tondaj_sl_814_driver_info entry in two places.
+ - src/hardware/tondaj-sl-814/ directory: Add api.c, protocol.c, protocol.h.
 
 See existing drivers or the 'new-driver' output for the details.
 
@@ -71,6 +70,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 +100,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.
-   Examples: LIBSIGROK_LIBSIGROK_H, LIBSIGROK_HARDWARE_ASIX_SIGMA_ASIX_SIGMA_H
+   Example: LIBSIGROK_HARDWARE_MIC_985XX_PROTOCOL_H
 
  - Consistently use the same naming convention for API functions:
    <libprefix>_<groupname>_<action>().
@@ -144,8 +149,13 @@ Doxygen
    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. 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 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.
@@ -153,12 +163,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)
-
 
 Testsuite
 ---------