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.

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.

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

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.

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

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

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

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.
  *

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

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,

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
 

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,

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
 

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

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

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.

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

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

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

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

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,

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;

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

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

src/std.c

@@ -21,8 +21,6 @@
  * @file
  *
  * Standard API helper functions.
- *
- * @internal
  */
 
 /* Needed for gettimeofday(), at least on FreeBSD. */

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

src/sw_limits.c

@@ -20,7 +20,6 @@
 /**
  * @file
  * Software limits helper functions
- * @internal
  */
 
 #include <config.h>

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,

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;