From: Uwe Hermann <redacted>
Date: Fri, 17 Feb 2012 19:44:19 +0000 (+0100)
Subject: sr: Random cosmetics, fix/amend Doxygen comments.
X-Git-Tag: libsigrok-0.1.0~117
X-Git-Url: https://sigrok.org/gitaction?a=commitdiff_plain;h=44dae539254e324e0330e194f9c775be3d761503;p=libsigrok.git

sr: Random cosmetics, fix/amend Doxygen comments.
---

diff --git a/device.c b/device.c
index b3b229c0..d806a113 100644
--- a/device.c
+++ b/device.c
@@ -120,7 +120,7 @@ SR_API GSList *sr_dev_list(void)
  * @return Pointer to the newly allocated device, or NULL upon errors.
  */
 SR_API struct sr_device *sr_dev_new(const struct sr_device_plugin *plugin,
-				       int plugin_index)
+				    int plugin_index)
 {
 	struct sr_device *device;
 
@@ -410,8 +410,8 @@ SR_API gboolean sr_dev_has_hwcap(const struct sr_device *device, int hwcap)
  *
  * @param device Pointer to the device to be checked. Must not be NULL.
  *               The device's 'plugin' field must not be NULL either.
- * @param id     The type of information.
- * @param data   The return value. Must not be NULL.
+ * @param id The type of information.
+ * @param data The return value. Must not be NULL.
  *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or SR_ERR
  *         upon other errors.
@@ -432,4 +432,3 @@ SR_API int sr_dev_info_get(const struct sr_device *device, int id,
 
 	return SR_OK;
 }
-
diff --git a/hwplugin.c b/hwplugin.c
index 212ab20c..368bb827 100644
--- a/hwplugin.c
+++ b/hwplugin.c
@@ -101,7 +101,7 @@ SR_PRIV int sr_hw_load_all(void)
 }
 
 /**
- * Returns the list of loaded hardware plugins.
+ * Return the list of loaded hardware plugins.
  *
  * The list of plugins is initialized from sr_init(), and can only be reset
  * by calling sr_exit().
@@ -110,7 +110,6 @@ SR_PRIV int sr_hw_load_all(void)
  */
 SR_API GSList *sr_hw_list(void)
 {
-
 	return plugins;
 }
 
@@ -266,8 +265,7 @@ SR_PRIV void sr_serial_dev_inst_free(
 /**
  * Find out if a hardware plugin has a specific capability.
  *
- * @param capabilities A NULL-terminated integer array of capabilities, as
- * returned by a plugin's get_capabilities() function.
+ * @param plugin The hardware plugin in which to search for the capability.
  * @param hwcap The capability to find in the list.
  *
  * @return TRUE if found, FALSE otherwise.
@@ -290,8 +288,8 @@ SR_API gboolean sr_hw_has_hwcap(struct sr_device_plugin *plugin, int hwcap)
  *
  * @param hwcap The capability to get.
  *
- * @return A struct with information about the parameter, or NULL
- * if not found.
+ * @return A pointer to a struct with information about the parameter, or NULL
+ *         if the capability was not found.
  */
 SR_API struct sr_hwcap_option *sr_hw_hwcap_get(int hwcap)
 {
diff --git a/input/chronovu_la8.c b/input/chronovu_la8.c
index 875b52bc..9c75a917 100644
--- a/input/chronovu_la8.c
+++ b/input/chronovu_la8.c
@@ -36,6 +36,7 @@
  * Max. value for divcount: 0xfe (2550ns sample period, 392.15kHz samplerate).
  *
  * @param divcount The divcount value as needed by the hardware.
+ *
  * @return The samplerate in Hz, or 0xffffffffffffffff upon errors.
  */
 static uint64_t divcount_to_samplerate(uint8_t divcount)
diff --git a/log.c b/log.c
index b5789537..f3199f57 100644
--- a/log.c
+++ b/log.c
@@ -55,6 +55,7 @@ static char sr_log_domain[LOGDOMAIN_MAXLEN + 1] = LOGDOMAIN_DEFAULT;
  *
  * @param loglevel The loglevel to set (SR_LOG_NONE, SR_LOG_ERR, SR_LOG_WARN,
  *                 SR_LOG_INFO, SR_LOG_DBG, or SR_LOG_SPEW).
+ *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid loglevel.
  */
 SR_API int sr_log_loglevel_set(int loglevel)
@@ -92,6 +93,7 @@ SR_API int sr_log_loglevel_get(void)
  *                  In order to not use a logdomain, pass an empty string.
  *                  The function makes its own copy of the input string, i.e.
  *                  the caller does not need to keep it around.
+ *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid logdomain.
  */
 SR_API int sr_log_logdomain_set(const char *logdomain)
@@ -131,6 +133,7 @@ SR_API char *sr_log_logdomain_get(void)
  *             pointer is only stored or passed on by libsigrok, and
  *             is never used or interpreted in any way. The pointer is allowed
  *             to be NULL if the caller doesn't need/want to pass any data.
+ *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
  */
 SR_API int sr_log_handler_set(sr_log_handler_t handler, void *data)
diff --git a/output/chronovu_la8.c b/output/chronovu_la8.c
index 830f4269..bb7fe4e7 100644
--- a/output/chronovu_la8.c
+++ b/output/chronovu_la8.c
@@ -36,6 +36,7 @@ struct context {
  * Check if the given samplerate is supported by the LA8 hardware.
  *
  * @param samplerate The samplerate (in Hz) to check.
+ *
  * @return 1 if the samplerate is supported/valid, 0 otherwise.
  */
 static int is_valid_samplerate(uint64_t samplerate)
@@ -61,6 +62,7 @@ static int is_valid_samplerate(uint64_t samplerate)
  * Max. value for divcount: 0xfe (2550ns sample period, 392.15kHz samplerate).
  *
  * @param samplerate The samplerate in Hz.
+ *
  * @return The divcount value as needed by the hardware, or 0xff upon errors.
  */
 static uint8_t samplerate_to_divcount(uint64_t samplerate)
diff --git a/session.c b/session.c
index 6a6cc923..75a2cb35 100644
--- a/session.c
+++ b/session.c
@@ -331,8 +331,8 @@ SR_API int sr_session_run(void)
 /**
  * Halt the current session.
  *
- * This requests the current session be stopped as soon as possible, for example
- * on receiving an SR_DF_END packet.
+ * This requests the current session be stopped as soon as possible, for
+ * example on receiving an SR_DF_END packet.
  *
  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
  */
@@ -388,7 +388,6 @@ SR_API int sr_session_stop(void)
  * Debug helper.
  *
  * @param packet The packet to show debugging information for.
- *
  */
 static void datafeed_dump(struct sr_datafeed_packet *packet)
 {
@@ -422,6 +421,7 @@ static void datafeed_dump(struct sr_datafeed_packet *packet)
  *
  * @param device TODO.
  * @param packet TODO.
+ *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
  */
 SR_PRIV int sr_session_bus(struct sr_device *device,
@@ -466,6 +466,7 @@ SR_PRIV int sr_session_bus(struct sr_device *device,
  * @param timeout TODO.
  * @param callback TODO.
  * @param user_data TODO.
+ *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
  *         SR_ERR_MALLOC upon memory allocation errors.
  */
@@ -514,6 +515,7 @@ SR_API int sr_session_source_add(int fd, int events, int timeout,
  * TODO: More error checks.
  *
  * @param fd TODO.
+ *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
  *         SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
  *         internal errors.
diff --git a/session_driver.c b/session_driver.c
index 7d2b9bda..01870c01 100644
--- a/session_driver.c
+++ b/session_driver.c
@@ -332,8 +332,7 @@ static int hw_start_acquisition(int device_index, gpointer session_device_id)
 	return SR_OK;
 }
 
-/* Not static, it's used elsewhere (via 'extern'). */
-struct sr_device_plugin session_driver = {
+SR_PRIV struct sr_device_plugin session_driver = {
 	"session",
 	"Session-emulating driver",
 	1,
diff --git a/session_file.c b/session_file.c
index c40e54fa..007e089c 100644
--- a/session_file.c
+++ b/session_file.c
@@ -28,7 +28,7 @@
 #include "sigrok-internal.h"
 
 extern struct sr_session *session;
-extern struct sr_device_plugin session_driver;
+extern SR_PRIV struct sr_device_plugin session_driver;
 
 /**
  * Load the session from the specified filename.
diff --git a/sigrok-internal.h b/sigrok-internal.h
index 8b939201..d8005443 100644
--- a/sigrok-internal.h
+++ b/sigrok-internal.h
@@ -63,8 +63,7 @@ SR_PRIV void sr_usb_dev_inst_free(struct sr_usb_device_instance *usb);
 /* Serial-specific instances */
 SR_PRIV struct sr_serial_device_instance *sr_serial_dev_inst_new(
 					const char *port, int fd);
-SR_PRIV void sr_serial_dev_inst_free(
-		struct sr_serial_device_instance *serial);
+SR_PRIV void sr_serial_dev_inst_free(struct sr_serial_device_instance *serial);
 
 /*--- log.c -----------------------------------------------------------------*/
 
@@ -83,7 +82,7 @@ SR_PRIV void sr_hw_cleanup_all(void);
 /*--- session.c -------------------------------------------------------------*/
 
 SR_PRIV int sr_session_bus(struct sr_device *device,
-			  struct sr_datafeed_packet *packet);
+			   struct sr_datafeed_packet *packet);
 
 /* Generic device instances */
 SR_PRIV struct sr_device_instance *sr_dev_inst_new(int index,
@@ -94,7 +93,7 @@ SR_PRIV void sr_dev_inst_free(struct sr_device_instance *sdi);
 
 SR_PRIV void sr_source_remove(int fd);
 SR_PRIV void sr_source_add(int fd, int events, int timeout,
-			  sr_receive_data_callback rcv_cb, void *user_data);
+			   sr_receive_data_callback rcv_cb, void *user_data);
 
 /*--- hardware/common/serial.c ----------------------------------------------*/
 
diff --git a/sigrok.h b/sigrok.h
index e08b2aed..c6809468 100644
--- a/sigrok.h
+++ b/sigrok.h
@@ -66,12 +66,12 @@ extern "C" {
 #define SR_HZ_TO_NS(n) (1000000000 / (n))
 
 /* libsigrok loglevels. */
-#define SR_LOG_NONE	           0 /**< Output no messages at all. */
+#define SR_LOG_NONE           0 /**< Output no messages at all. */
 #define SR_LOG_ERR            1 /**< Output error messages. */
-#define SR_LOG_WARN	           2 /**< Output warnings. */
-#define SR_LOG_INFO	           3 /**< Output informational messages. */
+#define SR_LOG_WARN           2 /**< Output warnings. */
+#define SR_LOG_INFO           3 /**< Output informational messages. */
 #define SR_LOG_DBG            4 /**< Output debug messages. */
-#define SR_LOG_SPEW	           5 /**< Output very noisy debug messages. */
+#define SR_LOG_SPEW           5 /**< Output very noisy debug messages. */
 
 /*
  * Use SR_API to mark public API symbols, and SR_PRIV for private symbols.
diff --git a/strutil.c b/strutil.c
index 5e8689e7..9cd194ed 100644
--- a/strutil.c
+++ b/strutil.c
@@ -30,6 +30,7 @@
  * E.g. a value of 3000000 would be converted to "3 MHz", 20000 to "20 kHz".
  *
  * @param samplerate The samplerate in Hz.
+ *
  * @return A g_try_malloc()ed string representation of the samplerate value,
  *         or NULL upon errors. The caller is responsible to g_free() the
  *         memory.
@@ -70,6 +71,7 @@ SR_API char *sr_samplerate_string(uint64_t samplerate)
  * E.g. a value of 3000000 would be converted to "3 us", 20000 to "50 ms".
  *
  * @param frequency The frequency in Hz.
+ *
  * @return A g_try_malloc()ed string representation of the frequency value,
  *         or NULL upon errors. The caller is responsible to g_free() the
  *         memory.
@@ -108,6 +110,7 @@ SR_API char *sr_period_string(uint64_t frequency)
  *
  * @param device TODO
  * @param triggerstring TODO
+ *
  * @return TODO
  */
 SR_API char **sr_parse_triggerstring(struct sr_device *device,
@@ -192,8 +195,8 @@ SR_API char **sr_parse_triggerstring(struct sr_device *device,
  *
  * @param sizestring A string containing a (decimal) size value.
  * @param size Pointer to uint64_t which will contain the string's size value.
- * @return SR_OK or error code
  *
+ * @return SR_OK upon success, SR_ERR upon errors.
  */
 SR_API int sr_parse_sizestring(const char *sizestring, uint64_t *size)
 {