From: Uwe Hermann <redacted>
Date: Wed, 25 Mar 2020 19:11:06 +0000 (+0100)
Subject: Doxygen: Fix various warnings.
X-Git-Url: https://sigrok.org/gitweb/?p=libsigrok.git;a=commitdiff_plain;h=6762401d2b992a7b10585653ab07ccf1a336fe05

Doxygen: Fix various warnings.

  src/resource.c:414: warning: unbalanced grouping commands

  conversion.c:81: warning: argument 'lo_thr' from the argument list of sr_a2l_schmitt_trigger has multiple @param documentation sections

  src/analog.c:611: warning: return value 'SR_ERR_ARG' of sr_rational_div has multiple documentation sections

  src/device.c:205: warning: explicit link request to 'TRUE' could not be resolved
  src/device.c:205: warning: explicit link request to 'FALSE' could not be resolved
  src/device.c:231: warning: explicit link request to 'TRUE' could not be resolved
  src/device.c:231: warning: explicit link request to 'FALSE' could not be resolved

  src/serial.c:246: warning: explicit link request to 'NULL' could not be resolved

  src/strutil.c:602: warning: explicit link request to 'NULL' could not be resolved

  src/device.c:94: warning: unable to resolve reference to 'sr_channel_free()' for \ref command

  src/strutil.c:597: warning: unable to resolve reference to 'sr_hexdump_free()' for \ref command
  src/strutil.c:622: warning: unable to resolve reference to 'sr_hexdump_new()' for \ref command

  src/device.c:430: warning: The following parameters of sr_dev_inst_channel_add(struct sr_dev_inst *sdi, int index, int type, const char *name) are not documented: parameter 'sdi'

  src/session.c:163: warning: The following parameters of fd_source_new(struct sr_session *session, void *key, gintptr fd, int events, int timeout_ms) are not documented: parameter 'events'
---

diff --git a/src/analog.c b/src/analog.c
index 4eda290f..a471f642 100644
--- a/src/analog.c
+++ b/src/analog.c
@@ -602,9 +602,8 @@ SR_API int sr_rational_mult(struct sr_rational *res, const struct sr_rational *a
  * @param[out] res Result.
  *
  * @retval SR_OK Success.
- * @retval SR_ERR_ARG Division by zero.
- * @retval SR_ERR_ARG Denominator of divisor too large.
- * @retval SR_ERR_ARG Resulting value too large.
+ * @retval SR_ERR_ARG Division by zero, denominator of divisor too large,
+ *                    or resulting value too large.
  *
  * @since 0.5.0
  */
diff --git a/src/conversion.c b/src/conversion.c
index 26af3d9c..ae84f41b 100644
--- a/src/conversion.c
+++ b/src/conversion.c
@@ -69,7 +69,7 @@ SR_API int sr_a2l_threshold(const struct sr_datafeed_analog *analog,
  *
  * @param analog The analog input values.
  * @param lo_thr The low threshold - result becomes 0 below it.
- * @param lo_thr The high threshold - result becomes 1 above it.
+ * @param hi_thr The high threshold - result becomes 1 above it.
  * @param state The internal converter state. Must contain the state of logic
  *        sample n-1, will contain the state of logic sample n+count upon exit.
  * @param output The converted output values; either 0 or 1. Must provide
diff --git a/src/device.c b/src/device.c
index 400b294b..5a144d97 100644
--- a/src/device.c
+++ b/src/device.c
@@ -92,7 +92,7 @@ SR_PRIV void sr_channel_free(struct sr_channel *ch)
 }
 
 /**
- * Wrapper around @ref sr_channel_free(), suitable for glib iterators.
+ * Wrapper around sr_channel_free(), suitable for glib iterators.
  *
  * @private
  */
@@ -203,7 +203,7 @@ SR_PRIV struct sr_channel *sr_next_enabled_channel(const struct sr_dev_inst *sdi
  * @param[in] ch1 First channel.
  * @param[in] ch2 Second channel.
  *
- * @return #TRUE upon differences or unexpected input, #FALSE otherwise.
+ * @return TRUE upon differences or unexpected input, FALSE otherwise.
  *
  * @private
  */
@@ -229,7 +229,7 @@ SR_PRIV gboolean sr_channels_differ(struct sr_channel *ch1, struct sr_channel *c
  * @param[in] l1 First channel list.
  * @param[in] l2 Second channel list.
  *
- * @return #TRUE upon differences or unexpected input, #FALSE otherwise.
+ * @return TRUE upon differences or unexpected input, FALSE otherwise.
  *
  * @private
  */
@@ -420,6 +420,7 @@ SR_API struct sr_dev_inst *sr_dev_inst_user_new(const char *vendor,
 /**
  * Add a new channel to the specified device instance.
  *
+ * @param[in] sdi Device instance to use. Must not be NULL.
  * @param[in] index @copydoc sr_channel::index
  * @param[in] type @copydoc sr_channel::type
  * @param[in] name @copydoc sr_channel::name
diff --git a/src/resource.c b/src/resource.c
index f2ef8c15..a30b4b3f 100644
--- a/src/resource.c
+++ b/src/resource.c
@@ -410,5 +410,3 @@ SR_PRIV void *sr_resource_load(struct sr_context *ctx,
 	*size = res_size;
 	return buf;
 }
-
-/** @} */
diff --git a/src/serial.c b/src/serial.c
index 7f08b7b3..1c0870d9 100644
--- a/src/serial.c
+++ b/src/serial.c
@@ -244,7 +244,7 @@ SR_PRIV int serial_drain(struct sr_serial_dev_inst *serial)
  * @retval SR_ERR_ARG Invalid parameters.
  * @retval SR_OK Successful registration.
  *
- * Callbacks get unregistered by specifying #NULL for the 'cb' parameter.
+ * Callbacks get unregistered by specifying NULL for the 'cb' parameter.
  *
  * @private
  */
diff --git a/src/session.c b/src/session.c
index 7e4bfbb3..5e48f4a5 100644
--- a/src/session.c
+++ b/src/session.c
@@ -157,7 +157,9 @@ static void fd_source_finalize(GSource *source)
  * @param session The session the event source belongs to.
  * @param key The key used to identify this source.
  * @param fd The file descriptor or HANDLE.
+ * @param events Events.
  * @param timeout_ms The timeout interval in ms, or -1 to wait indefinitely.
+ *
  * @return A new event source object, or NULL on failure.
  */
 static GSource *fd_source_new(struct sr_session *session, void *key,
diff --git a/src/strutil.c b/src/strutil.c
index 56ccaa09..5ee680e5 100644
--- a/src/strutil.c
+++ b/src/strutil.c
@@ -595,12 +595,12 @@ SR_API int sr_vsnprintf_ascii(char *buf, size_t buf_size,
 /**
  * Convert a sequence of bytes to its textual representation ("hex dump").
  *
- * Callers should free the allocated GString. See @ref sr_hexdump_free().
+ * Callers should free the allocated GString. See sr_hexdump_free().
  *
  * @param[in] data Pointer to the byte sequence to print.
  * @param[in] len Number of bytes to print.
  *
- * @return #NULL upon error, newly allocated GString pointer otherwise.
+ * @return NULL upon error, newly allocated GString pointer otherwise.
  *
  * @private
  */
@@ -620,7 +620,7 @@ SR_PRIV GString *sr_hexdump_new(const uint8_t *data, const size_t len)
 }
 
 /**
- * Free a hex dump text that was created by @ref sr_hexdump_new().
+ * Free a hex dump text that was created by sr_hexdump_new().
  *
  * @param[in] s Pointer to the GString to release.
  *