Coding style
------------
-This project is programmed using the Linux kernel coding style, see
-http://lxr.linux.no/linux/Documentation/CodingStyle for details.
+This project is programmed using the Linux kernel coding style:
+
+ https://www.kernel.org/doc/html/latest/process/coding-style.html
Please use the same style for any code contributions, thanks!
Contributions
-------------
- - Patches should be sent to the development mailinglist at
+ - In order to contribute you should ideally clone the git repository and
+ let us know (preferably via IRC, or via the mailing list) from where to
+ pull/review your changes. You can use github.com, or any other public git
+ hosting site.
+
+ - Alternatively, patches can be sent to the development mailinglist at
sigrok-devel@lists.sourceforge.net (please subscribe to the list first).
https://lists.sourceforge.net/lists/listinfo/sigrok-devel
- - Alternatively, you can also clone the git repository and let us know
- from where to pull/review your changes. You can use gitorious.org,
- github.com, or any other public git hosting site.
-
Adding a new hardware 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.
Doxygen
-------
+ - Use the @ notation for all Doxygen comments (e.g. @param, not \param).
+
+ - Do not use the @brief tag, it's unnecessary as we use JAVADOC_AUTOBRIEF.
+
+ - Generally use the following item order in Doxygen comments:
+ - Brief function description (1 line), followed by an empty line.
+ - Optionally, a longer function description (and another empty line).
+ - The list of parameter descriptions (@param).
+ - The return value description (@return or @retval).
+ - An optional @since tag (only for public SR_API functions).
+ - An optional @private tag (for private SR_PRIV functions).
+
+ - In @param lines, the name of the parameter is followed by a space and
+ then a sentence describing the parameter (starts with a capital letter,
+ ends with a full stop).
+
- 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 (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.
The @since tag should be the last one, i.e. it should come after @param,
@return, @see, and so on.
+ - Examples:
+
+/**
+ * Tell a hardware driver to scan for devices.
+ *
+ * In addition to the detection, the devices that are found are also
+ * initialized automatically. On some devices, this involves a firmware upload,
+ * or other such measures.
+ *
+ * The order in which the system is scanned for devices is not specified. The
+ * caller should not assume or rely on any specific order.
+ *
+ * Before calling sr_driver_scan(), the user must have previously initialized
+ * the driver by calling sr_driver_init().
+ *
+ * @param[in] driver The driver that should scan. Must be a pointer to one of
+ * the entries returned by sr_driver_list(). Must not be NULL.
+ * @param[in] options List of 'struct sr_hwopt' options to pass to the driver's
+ * scanner. Can be NULL/empty.
+ *
+ * @return A GSList * of 'struct sr_dev_inst', or NULL if no devices were
+ * found (or errors were encountered). This list must be freed by the
+ * caller using g_slist_free(), but without freeing the data pointed
+ * to in the list.
+ *
+ * @since 0.2.0
+ */
+
+/**
+ * Query value of a configuration key at the given driver or device instance.
+ *
+ * @param[in] driver The sr_dev_driver struct to query. Must not be NULL.
+ * @param[in] sdi (optional) If the key is specific to a device, this must
+ * contain a pointer to the struct sr_dev_inst to be checked.
+ * Otherwise it must be NULL. If sdi is != NULL, sdi->priv must
+ * also be != NULL.
+ * @param[in,out] data Pointer to a GVariant where the value will be stored.
+ * Must not be NULL. The caller is given ownership of the GVariant
+ * and must thus decrease the refcount after use. However if
+ * this function returns an error code, the field should be
+ * considered unused, and should not be unreferenced.
+ *
+ * @retval SR_OK Success.
+ * @retval SR_ERR Error.
+ * @retval SR_ERR_ARG The driver doesn't know that key, but this is not to be
+ * interpreted as an error by the caller; merely as an indication
+ * that it's not applicable.
+ *
+ * @since 0.3.0
+ * @private
+ */
+
Testsuite
---------
projects / libsigrok.git / blobdiff