X-Git-Url: http://sigrok.org/gitweb/?p=libsigrok.git;a=blobdiff_plain;f=HACKING;h=aa408ffb6cad15c90ca5ecc0250475886b94a9e4;hp=5978863b6d3f99559dbf24e1b535355666b7451c;hb=HEAD;hpb=b4698e4d617483bc0157b62b4be4153535b45701

diff --git a/HACKING b/HACKING
index 5978863b..2d9abe95 100644
--- a/HACKING
+++ b/HACKING
@@ -61,8 +61,9 @@ 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:
 
- - Makefile.am: Add HW_TONDAJ_SL_814 and add to libsigrok_la_SOURCES.
- - configure.ac: Add a DRIVER() and DRIVER2() call.
+ - Makefile.am: Add to src_libdrivers_la_SOURCES under the HW_TONDAJ_SL_814
+   condition.
+ - configure.ac: Add an SR_DRIVER() 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.
 
@@ -78,6 +79,9 @@ Random notes
  - Generally avoid assigning values to variables at declaration time,
    especially so for complex and/or run-time dependent values.
 
+ - Separate assignments from control flow. Example: Avoid the pattern
+   if (var = func()) {...}  as it complicates review and maintenance.
+
  - 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).
@@ -94,6 +98,9 @@ Random notes
    Do use g_try_malloc() or g_try_malloc0() for large (>= 1MB) allocations
    and check the return value.
 
+ - Endianness conversion: Prefer the common helpers that are provided in
+   libsigrok-internal.h, such as read_u16be() etc.
+
  - You should never print any messages (neither to stdout nor stderr nor
    elsewhere) "manually" via e.g. printf() or g_log() or similar functions.
    Only sr_err()/sr_warn()/sr_info()/sr_dbg()/sr_spew() should be used.
@@ -163,7 +170,9 @@ Doxygen
 
  - Mark private functions (SR_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.
+   don't need to be marked like this. Functions in non-public files that
+   are explicitly excluded in Doxyfile don't need to be marked either.
+   Don't use @internal, always use @private instead.
 
  - Mark private variables/#defines with /** @cond PRIVATE */ and
    /** @endcond */, so that Doxygen doesn't include them in the output.