Browse Source

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.
master
Uwe Hermann 2 years ago
parent
commit
82b9f3d116
  1. 4
      HACKING
  2. 2
      src/bt/bt_bluez.c
  3. 2
      src/conversion.c
  4. 6
      src/device.c
  5. 2
      src/dmm/asycii.c
  6. 2
      src/dmm/eev121gw.c
  7. 1
      src/dmm/metex14.c
  8. 4
      src/drivers.c
  9. 4
      src/input/input.c
  10. 6
      src/libsigrok-internal.h
  11. 2
      src/output/output.c
  12. 4
      src/scpi.h
  13. 12
      src/serial.c
  14. 4
      src/serial_bt.c
  15. 6
      src/serial_hid.c
  16. 2
      src/serial_hid_bu86x.c
  17. 2
      src/serial_hid_ch9325.c
  18. 2
      src/serial_hid_cp2110.c
  19. 2
      src/serial_hid_victor.c
  20. 4
      src/serial_libsp.c
  21. 1
      src/session.c
  22. 2
      src/session_file.c
  23. 4
      src/soft-trigger.c
  24. 2
      src/std.c
  25. 30
      src/strutil.c
  26. 1
      src/sw_limits.c
  27. 2
      src/transform/transform.c
  28. 4
      src/trigger.c
  29. 1
      src/usb.c

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

2
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

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

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

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

2
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

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

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

4
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,

6
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

2
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,

4
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

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

4
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

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

2
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

2
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

2
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

2
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

4
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,

1
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;

2
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

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

2
src/std.c

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

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

1
src/sw_limits.c

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

2
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,

4
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

1
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;

Loading…
Cancel
Save