From: Uwe Hermann <redacted>
Date: Tue, 24 Mar 2020 19:09:02 +0000 (+0100)
Subject: Doxygen: Properly mark a few symbols as private.
X-Git-Url: https://sigrok.org/gitaction?a=commitdiff_plain;h=82b9f3d116ce0c982291a2dfdd15cd8a1c4cc16e;p=libsigrok.git

Doxygen: Properly mark a few symbols as private.

(otherwise these end up in the API docs)

Remove all @internal markings, only use @private where needed.
---

diff --git a/HACKING b/HACKING
index a5aa8d66..9d71c55c 100644
--- a/HACKING
+++ b/HACKING
@@ -164,7 +164,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.
diff --git a/src/bt/bt_bluez.c b/src/bt/bt_bluez.c
index e3872734..f64ba59d 100644
--- a/src/bt/bt_bluez.c
+++ b/src/bt/bt_bluez.c
@@ -87,9 +87,7 @@
 #include <libsigrok/libsigrok.h>
 #include "libsigrok-internal.h"
 
-/** @cond PRIVATE */
 #define LOG_PREFIX "bt-bluez"
-/** @endcond */
 
 #define CONNECT_BLE_TIMEOUT	20	/* Connect timeout in seconds. */
 #define STORE_MAC_REVERSE	1
diff --git a/src/conversion.c b/src/conversion.c
index 3d969308..26af3d9c 100644
--- a/src/conversion.c
+++ b/src/conversion.c
@@ -26,7 +26,9 @@
 #include <libsigrok/libsigrok.h>
 #include "libsigrok-internal.h"
 
+/** @cond PRIVATE */
 #define LOG_PREFIX "conv"
+/** @endcond */
 
 /**
  * Convert analog values to logic values by using a fixed threshold.
diff --git a/src/device.c b/src/device.c
index 4642e5f0..400b294b 100644
--- a/src/device.c
+++ b/src/device.c
@@ -93,6 +93,8 @@ SR_PRIV void sr_channel_free(struct sr_channel *ch)
 
 /**
  * Wrapper around @ref sr_channel_free(), suitable for glib iterators.
+ *
+ * @private
  */
 SR_PRIV void sr_channel_free_cb(void *p)
 {
@@ -203,7 +205,7 @@ SR_PRIV struct sr_channel *sr_next_enabled_channel(const struct sr_dev_inst *sdi
  *
  * @return #TRUE upon differences or unexpected input, #FALSE otherwise.
  *
- * @internal
+ * @private
  */
 SR_PRIV gboolean sr_channels_differ(struct sr_channel *ch1, struct sr_channel *ch2)
 {
@@ -229,7 +231,7 @@ SR_PRIV gboolean sr_channels_differ(struct sr_channel *ch1, struct sr_channel *c
  *
  * @return #TRUE upon differences or unexpected input, #FALSE otherwise.
  *
- * @internal
+ * @private
  */
 SR_PRIV gboolean sr_channel_lists_differ(GSList *l1, GSList *l2)
 {
diff --git a/src/dmm/asycii.c b/src/dmm/asycii.c
index b34ec70b..96a462c5 100644
--- a/src/dmm/asycii.c
+++ b/src/dmm/asycii.c
@@ -455,8 +455,6 @@ static gboolean flags_valid(const struct asycii_info *info)
  * without the PC's intervention.
  *
  * @param[in]	serial The serial connection.
- *
- * @private
  */
 SR_PRIV int sr_asycii_packet_request(struct sr_serial_dev_inst *serial)
 {
diff --git a/src/dmm/eev121gw.c b/src/dmm/eev121gw.c
index f1a0070a..7dfba8d0 100644
--- a/src/dmm/eev121gw.c
+++ b/src/dmm/eev121gw.c
@@ -22,8 +22,6 @@
  *
  * EEVblog 121GW 19-bytes binary protocol parser.
  *
- * @internal
- *
  * Note that this protocol is different from other meters. We need not
  * decode the LCD presentation (segments a-g and dot of seven segment
  * displays). Neither need we decode a textual presentation consisting
diff --git a/src/dmm/metex14.c b/src/dmm/metex14.c
index d363c550..5c4ed085 100644
--- a/src/dmm/metex14.c
+++ b/src/dmm/metex14.c
@@ -22,7 +22,6 @@
  *
  * Metex 14-bytes ASCII protocol parser.
  *
- * @internal
  * This should work for various multimeters which use this kind of protocol,
  * even though there is some variation in which modes each DMM supports.
  *
diff --git a/src/drivers.c b/src/drivers.c
index 7641e24d..30d6308a 100644
--- a/src/drivers.c
+++ b/src/drivers.c
@@ -34,10 +34,12 @@
 SR_PRIV extern const struct sr_dev_driver *sr_driver_list__start[];
 SR_PRIV extern const struct sr_dev_driver *sr_driver_list__stop[];
 
-/** @private
+/**
  * Initialize the driver list in a fresh libsigrok context.
  *
  * @param ctx Pointer to a libsigrok context struct. Must not be NULL.
+ *
+ * @private
  */
 SR_API void sr_drivers_init(struct sr_context *ctx)
 {
diff --git a/src/input/input.c b/src/input/input.c
index 282084ca..48dbb157 100644
--- a/src/input/input.c
+++ b/src/input/input.c
@@ -29,7 +29,9 @@
 #define LOG_PREFIX "input"
 /** @endcond */
 
+/** @cond PRIVATE */
 #define CHUNK_SIZE	(4 * 1024 * 1024)
+/** @endcond */
 
 /**
  * @file
@@ -70,7 +72,7 @@ extern SR_PRIV struct sr_input_module input_wav;
 extern SR_PRIV struct sr_input_module input_raw_analog;
 extern SR_PRIV struct sr_input_module input_logicport;
 extern SR_PRIV struct sr_input_module input_null;
-/* @endcond */
+/** @endcond */
 
 static const struct sr_input_module *input_module_list[] = {
 	&input_binary,
diff --git a/src/libsigrok-internal.h b/src/libsigrok-internal.h
index c57f2058..140d11e1 100644
--- a/src/libsigrok-internal.h
+++ b/src/libsigrok-internal.h
@@ -17,12 +17,6 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/**
- * @file
- *
- * @internal
- */
-
 #ifndef LIBSIGROK_LIBSIGROK_INTERNAL_H
 #define LIBSIGROK_LIBSIGROK_INTERNAL_H
 
diff --git a/src/output/output.c b/src/output/output.c
index 1a134eb2..6f02b680 100644
--- a/src/output/output.c
+++ b/src/output/output.c
@@ -66,7 +66,7 @@ extern SR_PRIV struct sr_output_module output_srzip;
 extern SR_PRIV struct sr_output_module output_wav;
 extern SR_PRIV struct sr_output_module output_wavedrom;
 extern SR_PRIV struct sr_output_module output_null;
-/* @endcond */
+/** @endcond */
 
 static const struct sr_output_module *output_module_list[] = {
 	&output_ascii,
diff --git a/src/scpi.h b/src/scpi.h
index e8bb33f4..312f5e8a 100644
--- a/src/scpi.h
+++ b/src/scpi.h
@@ -17,10 +17,6 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** @file
-  * @internal
-  */
-
 #ifndef LIBSIGROK_SCPI_H
 #define LIBSIGROK_SCPI_H
 
diff --git a/src/serial.c b/src/serial.c
index 7f9de4f6..7f08b7b3 100644
--- a/src/serial.c
+++ b/src/serial.c
@@ -245,6 +245,8 @@ SR_PRIV int serial_drain(struct sr_serial_dev_inst *serial)
  * @retval SR_OK Successful registration.
  *
  * Callbacks get unregistered by specifying #NULL for the 'cb' parameter.
+ *
+ * @private
  */
 SR_PRIV int serial_set_read_chunk_cb(struct sr_serial_dev_inst *serial,
 	serial_rx_chunk_callback cb, void *cb_data)
@@ -264,7 +266,7 @@ SR_PRIV int serial_set_read_chunk_cb(struct sr_serial_dev_inst *serial,
  *
  * @param[in] serial Previously opened serial port instance.
  *
- * @internal
+ * @private
  */
 SR_PRIV void sr_ser_discard_queued_data(struct sr_serial_dev_inst *serial)
 {
@@ -280,7 +282,7 @@ SR_PRIV void sr_ser_discard_queued_data(struct sr_serial_dev_inst *serial)
  *
  * @param[in] serial Previously opened serial port instance.
  *
- * @internal
+ * @private
  */
 SR_PRIV size_t sr_ser_has_queued_data(struct sr_serial_dev_inst *serial)
 {
@@ -298,7 +300,7 @@ SR_PRIV size_t sr_ser_has_queued_data(struct sr_serial_dev_inst *serial)
  * @param[in] data Pointer to data bytes to queue.
  * @param[in] len Number of data bytes to queue.
  *
- * @internal
+ * @private
  */
 SR_PRIV void sr_ser_queue_rx_data(struct sr_serial_dev_inst *serial,
 	const uint8_t *data, size_t len)
@@ -320,7 +322,7 @@ SR_PRIV void sr_ser_queue_rx_data(struct sr_serial_dev_inst *serial,
  * @param[out] data Pointer to store retrieved data bytes into.
  * @param[in] len Number of data bytes to retrieve.
  *
- * @internal
+ * @private
  */
 SR_PRIV size_t sr_ser_unqueue_rx_data(struct sr_serial_dev_inst *serial,
 	uint8_t *data, size_t len)
@@ -355,6 +357,8 @@ SR_PRIV size_t sr_ser_unqueue_rx_data(struct sr_serial_dev_inst *serial,
  *
  * Returns 0 if no receive data is available, or if the amount of
  * available receive data cannot get determined.
+ *
+ * @private
  */
 SR_PRIV size_t serial_has_receive_data(struct sr_serial_dev_inst *serial)
 {
diff --git a/src/serial_bt.c b/src/serial_bt.c
index 678a0ce2..42d6289a 100644
--- a/src/serial_bt.c
+++ b/src/serial_bt.c
@@ -24,9 +24,7 @@
 #include <string.h>
 #include <memory.h>
 
-/** @cond PRIVATE */
 #define LOG_PREFIX "serial-bt"
-/** @endcond */
 
 #ifdef HAVE_SERIAL_COMM
 #ifdef HAVE_BLUETOOTH
@@ -109,8 +107,6 @@ static const char *conn_name_text(enum ser_bt_conn_t type)
  *
  * @return 0 upon success, non-zero upon failure.
  *
- * @internal
- *
  * Summary of parsing rules as they are implemented:
  * - Implementor's note: Automatic scan for available devices is not
  *   yet implemented. So strictly speaking some parts of the input
diff --git a/src/serial_hid.c b/src/serial_hid.c
index 86361d92..6245aca4 100644
--- a/src/serial_hid.c
+++ b/src/serial_hid.c
@@ -31,9 +31,7 @@
 #include <windows.h> /* for HANDLE */
 #endif
 
-/** @cond PRIVATE */
 #define LOG_PREFIX "serial-hid"
-/** @endcond */
 
 #ifdef HAVE_SERIAL_COMM
 
@@ -665,8 +663,6 @@ static int try_open_path(struct sr_serial_dev_inst *serial, const char *path)
  * @return 0 upon success, non-zero upon failure. Fills the *_ref output
  * values.
  *
- * @internal
- *
  * Summary of parsing rules as they are implemented:
  * - Insist on the "hid" prefix. Accept "hid" alone without any other
  *   additional field.
@@ -845,8 +841,6 @@ static GSList *list_paths_for_vids_pids(const struct vid_pid_item *vid_pids)
  * @retval SR_OK upon success
  * @retval SR_ERR_* upon failure.
  *
- * @internal
- *
  * This routine fills in blanks which the conn= spec parser left open.
  * When not specified yet, the HID chip type gets determined. When a
  * serial number was specified, then search the corresponding device.
diff --git a/src/serial_hid_bu86x.c b/src/serial_hid_bu86x.c
index 4009c334..c103eefa 100644
--- a/src/serial_hid_bu86x.c
+++ b/src/serial_hid_bu86x.c
@@ -40,9 +40,7 @@
 #include "serial_hid.h"
 #include <string.h>
 
-/** @cond PRIVATE */
 #define LOG_PREFIX "serial-bu86x"
-/** @endcond */
 
 #ifdef HAVE_SERIAL_COMM
 #ifdef HAVE_LIBHIDAPI
diff --git a/src/serial_hid_ch9325.c b/src/serial_hid_ch9325.c
index ce4a4f67..3c8accb7 100644
--- a/src/serial_hid_ch9325.c
+++ b/src/serial_hid_ch9325.c
@@ -24,9 +24,7 @@
 #include "serial_hid.h"
 #include <string.h>
 
-/** @cond PRIVATE */
 #define LOG_PREFIX "serial-ch9325"
-/** @endcond */
 
 #ifdef HAVE_SERIAL_COMM
 #ifdef HAVE_LIBHIDAPI
diff --git a/src/serial_hid_cp2110.c b/src/serial_hid_cp2110.c
index d588ca20..72a7aa98 100644
--- a/src/serial_hid_cp2110.c
+++ b/src/serial_hid_cp2110.c
@@ -25,9 +25,7 @@
 #include "serial_hid.h"
 #include <string.h>
 
-/** @cond PRIVATE */
 #define LOG_PREFIX "serial-cp2110"
-/** @endcond */
 
 #ifdef HAVE_SERIAL_COMM
 #ifdef HAVE_LIBHIDAPI
diff --git a/src/serial_hid_victor.c b/src/serial_hid_victor.c
index a304980e..684a851d 100644
--- a/src/serial_hid_victor.c
+++ b/src/serial_hid_victor.c
@@ -40,9 +40,7 @@
 #include "serial_hid.h"
 #include <string.h>
 
-/** @cond PRIVATE */
 #define LOG_PREFIX "serial-victor"
-/** @endcond */
 
 #ifdef HAVE_SERIAL_COMM
 #ifdef HAVE_LIBHIDAPI
diff --git a/src/serial_libsp.c b/src/serial_libsp.c
index b16cd12e..f5a2b74b 100644
--- a/src/serial_libsp.c
+++ b/src/serial_libsp.c
@@ -31,9 +31,7 @@
 #include <windows.h> /* for HANDLE */
 #endif
 
-/** @cond PRIVATE */
 #define LOG_PREFIX "serial-libsp"
-/** @endcond */
 
 /**
  * @file
@@ -282,13 +280,11 @@ static int sr_ser_libsp_set_params(struct sr_serial_dev_inst *serial,
 	return SR_OK;
 }
 
-/** @cond PRIVATE */
 #ifdef G_OS_WIN32
 typedef HANDLE event_handle;
 #else
 typedef int event_handle;
 #endif
-/** @endcond */
 
 static int sr_ser_libsp_source_add_int(struct sr_serial_dev_inst *serial,
 	int events,
diff --git a/src/session.c b/src/session.c
index 0940617c..7e4bfbb3 100644
--- a/src/session.c
+++ b/src/session.c
@@ -53,7 +53,6 @@ struct datafeed_callback {
 
 /** Custom GLib event source for generic descriptor I/O.
  * @see https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html
- * @internal
  */
 struct fd_source {
 	GSource base;
diff --git a/src/session_file.c b/src/session_file.c
index 7a2010e4..dc4012d9 100644
--- a/src/session_file.c
+++ b/src/session_file.c
@@ -43,7 +43,9 @@
  * @{
  */
 
+/** @cond PRIVATE */
 extern SR_PRIV struct sr_dev_driver session_driver;
+/** @endcond */
 static int session_driver_initialized = 0;
 
 #if !HAVE_ZIP_DISCARD
diff --git a/src/soft-trigger.c b/src/soft-trigger.c
index 245eb4ff..0c5bb466 100644
--- a/src/soft-trigger.c
+++ b/src/soft-trigger.c
@@ -22,9 +22,9 @@
 #include <libsigrok/libsigrok.h>
 #include "libsigrok-internal.h"
 
-/* @cond PRIVATE */
+/** @cond PRIVATE */
 #define LOG_PREFIX "soft-trigger"
-/* @endcond */
+/** @endcond */
 
 SR_PRIV int logic_channel_unitsize(GSList *channels)
 {
diff --git a/src/std.c b/src/std.c
index d93466e2..581e2e46 100644
--- a/src/std.c
+++ b/src/std.c
@@ -21,8 +21,6 @@
  * @file
  *
  * Standard API helper functions.
- *
- * @internal
  */
 
 /* Needed for gettimeofday(), at least on FreeBSD. */
diff --git a/src/strutil.c b/src/strutil.c
index 93e424ee..56ccaa09 100644
--- a/src/strutil.c
+++ b/src/strutil.c
@@ -18,7 +18,9 @@
  */
 
 /* Needed for POSIX.1-2008 locale functions */
+/** @cond PRIVATE */
 #define _XOPEN_SOURCE 700
+/** @endcond */
 #include <config.h>
 #include <ctype.h>
 #include <locale.h>
@@ -55,8 +57,6 @@
  */
 
 /**
- * @private
- *
  * Convert a string representation of a numeric value (base 10) to a long integer. The
  * conversion is strict and will fail if the complete string does not represent
  * a valid long integer. The function sets errno according to the details of the
@@ -67,6 +67,8 @@
  *
  * @retval SR_OK Conversion successful.
  * @retval SR_ERR Failure.
+ *
+ * @private
  */
 SR_PRIV int sr_atol(const char *str, long *ret)
 {
@@ -90,8 +92,6 @@ SR_PRIV int sr_atol(const char *str, long *ret)
 }
 
 /**
- * @private
- *
  * Convert a string representation of a numeric value (base 10) to an integer. The
  * conversion is strict and will fail if the complete string does not represent
  * a valid integer. The function sets errno according to the details of the
@@ -102,6 +102,8 @@ SR_PRIV int sr_atol(const char *str, long *ret)
  *
  * @retval SR_OK Conversion successful.
  * @retval SR_ERR Failure.
+ *
+ * @private
  */
 SR_PRIV int sr_atoi(const char *str, int *ret)
 {
@@ -120,8 +122,6 @@ SR_PRIV int sr_atoi(const char *str, int *ret)
 }
 
 /**
- * @private
- *
  * Convert a string representation of a numeric value to a double. The
  * conversion is strict and will fail if the complete string does not represent
  * a valid double. The function sets errno according to the details of the
@@ -132,6 +132,8 @@ SR_PRIV int sr_atoi(const char *str, int *ret)
  *
  * @retval SR_OK Conversion successful.
  * @retval SR_ERR Failure.
+ *
+ * @private
  */
 SR_PRIV int sr_atod(const char *str, double *ret)
 {
@@ -155,8 +157,6 @@ SR_PRIV int sr_atod(const char *str, double *ret)
 }
 
 /**
- * @private
- *
  * Convert a string representation of a numeric value to a float. The
  * conversion is strict and will fail if the complete string does not represent
  * a valid float. The function sets errno according to the details of the
@@ -167,6 +167,8 @@ SR_PRIV int sr_atod(const char *str, double *ret)
  *
  * @retval SR_OK Conversion successful.
  * @retval SR_ERR Failure.
+ *
+ * @private
  */
 SR_PRIV int sr_atof(const char *str, float *ret)
 {
@@ -185,8 +187,6 @@ SR_PRIV int sr_atof(const char *str, float *ret)
 }
 
 /**
- * @private
- *
  * Convert a string representation of a numeric value to a double. The
  * conversion is strict and will fail if the complete string does not represent
  * a valid double. The function sets errno according to the details of the
@@ -197,6 +197,8 @@ SR_PRIV int sr_atof(const char *str, float *ret)
  *
  * @retval SR_OK Conversion successful.
  * @retval SR_ERR Failure.
+ *
+ * @private
  */
 SR_PRIV int sr_atod_ascii(const char *str, double *ret)
 {
@@ -217,8 +219,6 @@ SR_PRIV int sr_atod_ascii(const char *str, double *ret)
 }
 
 /**
- * @private
- *
  * Convert a string representation of a numeric value to a float. The
  * conversion is strict and will fail if the complete string does not represent
  * a valid float. The function sets errno according to the details of the
@@ -229,6 +229,8 @@ SR_PRIV int sr_atod_ascii(const char *str, double *ret)
  *
  * @retval SR_OK Conversion successful.
  * @retval SR_ERR Failure.
+ *
+ * @private
  */
 SR_PRIV int sr_atof_ascii(const char *str, float *ret)
 {
@@ -599,6 +601,8 @@ SR_API int sr_vsnprintf_ascii(char *buf, size_t buf_size,
  * @param[in] len Number of bytes to print.
  *
  * @return #NULL upon error, newly allocated GString pointer otherwise.
+ *
+ * @private
  */
 SR_PRIV GString *sr_hexdump_new(const uint8_t *data, const size_t len)
 {
@@ -619,6 +623,8 @@ 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().
  *
  * @param[in] s Pointer to the GString to release.
+ *
+ * @private
  */
 SR_PRIV void sr_hexdump_free(GString *s)
 {
diff --git a/src/sw_limits.c b/src/sw_limits.c
index 6e1c4c14..37c28667 100644
--- a/src/sw_limits.c
+++ b/src/sw_limits.c
@@ -20,7 +20,6 @@
 /**
  * @file
  * Software limits helper functions
- * @internal
  */
 
 #include <config.h>
diff --git a/src/transform/transform.c b/src/transform/transform.c
index 6334ed21..ea007297 100644
--- a/src/transform/transform.c
+++ b/src/transform/transform.c
@@ -45,7 +45,7 @@
 extern SR_PRIV struct sr_transform_module transform_nop;
 extern SR_PRIV struct sr_transform_module transform_scale;
 extern SR_PRIV struct sr_transform_module transform_invert;
-/* @endcond */
+/** @endcond */
 
 static const struct sr_transform_module *transform_module_list[] = {
 	&transform_nop,
diff --git a/src/trigger.c b/src/trigger.c
index c8e13d2f..51d8368a 100644
--- a/src/trigger.c
+++ b/src/trigger.c
@@ -21,9 +21,9 @@
 #include <libsigrok/libsigrok.h>
 #include "libsigrok-internal.h"
 
-/* * @cond PRIVATE */
+/** @cond PRIVATE */
 #define LOG_PREFIX "trigger"
-/* * @endcond */
+/** @endcond */
 
 /**
  * @file
diff --git a/src/usb.c b/src/usb.c
index 8a8f0ca5..93286e8a 100644
--- a/src/usb.c
+++ b/src/usb.c
@@ -38,7 +38,6 @@ typedef int libusb_os_handle;
 #endif
 
 /** Custom GLib event source for libusb I/O.
- * @internal
  */
 struct usb_source {
 	GSource base;