sr: Random cosmetics, fix/amend Doxygen comments.

device.c

@@ -432,4 +432,3 @@ SR_API int sr_dev_info_get(const struct sr_device *device, int id,
 
 	return SR_OK;
 }
-

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
+ * @param plugin The hardware plugin in which to search for the capability.
- * returned by a plugin's get_capabilities() function.
  * @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
+ * @return A pointer to a struct with information about the parameter, or NULL
- * if not found.
+ *         if the capability was not found.
  */
 SR_API struct sr_hwcap_option *sr_hw_hwcap_get(int hwcap)
 {

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)

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)

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)

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
+ * This requests the current session be stopped as soon as possible, for
- * on receiving an SR_DF_END packet.
+ * 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.

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'). */
+SR_PRIV struct sr_device_plugin session_driver = {
-struct sr_device_plugin session_driver = {
 	"session",
 	"Session-emulating driver",
 	1,

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.

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(
+SR_PRIV void sr_serial_dev_inst_free(struct sr_serial_device_instance *serial);
-		struct sr_serial_device_instance *serial);
 
 /*--- log.c -----------------------------------------------------------------*/
 

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)
 {