Commit b4bd7088 authored by Uwe Hermann's avatar Uwe Hermann

Doxygen: Mark non-public stuff for exclusion.

 - /** @private */ can be used for functions, and /** @cond PRIVATE */ and
   /** @endcond */ for variables or #defines.

 - Document the above in HACKING.
parent 5b30cca7
......@@ -71,10 +71,22 @@ Random notes
should end with "_all", e.g. "_remove_all", "_get_all", and so on.
Use "_remove_all" in favor of "_clear" for consistency.
Doxygen
-------
- In Doxygen comments, put an empty line between the block of @param lines
and the final @return line. The @param lines themselves (if there is more
than one) are not separated by empty lines.
- 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.
- Mark private variables/#defines with /** @cond PRIVATE */ and
/** @endcond */, so that Doxygen doesn't include them in the output.
Variables that are "static" don't need to be marked like this.
Release engineering
-------------------
......
......@@ -22,6 +22,7 @@
#include "libsigrok.h"
#include "libsigrok-internal.h"
/** @private */
SR_PRIV struct sr_probe *sr_probe_new(int index, int type,
gboolean enabled, const char *name)
{
......@@ -184,6 +185,7 @@ SR_API gboolean sr_dev_has_hwcap(const struct sr_dev_inst *sdi, int hwcap)
return FALSE;
}
/** @private */
SR_PRIV struct sr_dev_inst *sr_dev_inst_new(int index, int status,
const char *vendor, const char *model, const char *version)
{
......@@ -207,6 +209,7 @@ SR_PRIV struct sr_dev_inst *sr_dev_inst_new(int index, int status,
return sdi;
}
/** @private */
SR_PRIV void sr_dev_inst_free(struct sr_dev_inst *sdi)
{
struct sr_probe *probe;
......@@ -228,6 +231,7 @@ SR_PRIV void sr_dev_inst_free(struct sr_dev_inst *sdi)
#ifdef HAVE_LIBUSB_1_0
/** @private */
SR_PRIV struct sr_usb_dev_inst *sr_usb_dev_inst_new(uint8_t bus,
uint8_t address, struct libusb_device_handle *hdl)
{
......@@ -245,6 +249,7 @@ SR_PRIV struct sr_usb_dev_inst *sr_usb_dev_inst_new(uint8_t bus,
return udi;
}
/** @private */
SR_PRIV void sr_usb_dev_inst_free(struct sr_usb_dev_inst *usb)
{
/* Avoid compiler warnings. */
......@@ -255,6 +260,7 @@ SR_PRIV void sr_usb_dev_inst_free(struct sr_usb_dev_inst *usb)
#endif
/** @private */
SR_PRIV struct sr_serial_dev_inst *sr_serial_dev_inst_new(const char *port,
int fd)
{
......@@ -271,6 +277,7 @@ SR_PRIV struct sr_serial_dev_inst *sr_serial_dev_inst_new(const char *port,
return serial;
}
/** @private */
SR_PRIV void sr_serial_dev_inst_free(struct sr_serial_dev_inst *serial)
{
g_free(serial->port);
......
......@@ -53,6 +53,7 @@ static struct sr_hwcap_option sr_devopts[] = {
{0, 0, NULL, NULL},
};
/** @cond PRIVATE */
#ifdef HAVE_LA_DEMO
extern SR_PRIV struct sr_dev_driver demo_driver_info;
#endif
......@@ -92,6 +93,7 @@ extern SR_PRIV struct sr_dev_driver flukedmm_driver_info;
#ifdef HAVE_HW_RADIOSHACK_DMM
extern SR_PRIV struct sr_dev_driver radioshackdmm_driver_info;
#endif
/** @endcond */
static struct sr_dev_driver *drivers_list[] = {
#ifdef HAVE_LA_DEMO
......@@ -190,6 +192,7 @@ SR_API GSList *sr_driver_scan(struct sr_dev_driver *driver, GSList *options)
return NULL;
}
/** @private */
SR_PRIV void sr_hw_cleanup_all(void)
{
int i;
......@@ -341,11 +344,13 @@ SR_API const struct sr_hwcap_option *sr_devopt_name_get(const char *optname)
/* Unnecessary level of indirection follows. */
/** @private */
SR_PRIV int sr_source_remove(int fd)
{
return sr_session_source_remove(fd);
}
/** @private */
SR_PRIV int sr_source_add(int fd, int events, int timeout,
sr_receive_data_callback_t cb, void *cb_data)
{
......
......@@ -20,8 +20,10 @@
#include "libsigrok.h"
#include "libsigrok-internal.h"
/** @cond PRIVATE */
extern SR_PRIV struct sr_input_format input_chronovu_la8;
extern SR_PRIV struct sr_input_format input_binary;
/* @endcond */
static struct sr_input_format *input_module_list[] = {
&input_chronovu_la8,
......
......@@ -23,6 +23,12 @@
#include "libsigrok.h"
#include "libsigrok-internal.h"
/**
* @file
*
* Logging support.
*/
/* Currently selected libsigrok loglevel. Default: SR_LOG_WARN. */
static int sr_loglevel = SR_LOG_WARN; /* Show errors+warnings per default. */
......@@ -40,8 +46,10 @@ static sr_log_callback_t sr_log_callback = sr_logv;
static void *sr_log_callback_data = NULL;
/* Log domain (a short string that is used as prefix for all messages). */
/** @cond PRIVATE */
#define LOGDOMAIN_MAXLEN 30
#define LOGDOMAIN_DEFAULT "sr: "
/** @endcond */
static char sr_log_domain[LOGDOMAIN_MAXLEN + 1] = LOGDOMAIN_DEFAULT;
/**
......@@ -190,6 +198,7 @@ static int sr_logv(void *cb_data, int loglevel, const char *format, va_list args
return ret;
}
/** @private */
SR_PRIV int sr_log(int loglevel, const char *format, ...)
{
int ret;
......@@ -202,6 +211,7 @@ SR_PRIV int sr_log(int loglevel, const char *format, ...)
return ret;
}
/** @private */
SR_PRIV int sr_spew(const char *format, ...)
{
int ret;
......@@ -214,6 +224,7 @@ SR_PRIV int sr_spew(const char *format, ...)
return ret;
}
/** @private */
SR_PRIV int sr_dbg(const char *format, ...)
{
int ret;
......@@ -226,6 +237,7 @@ SR_PRIV int sr_dbg(const char *format, ...)
return ret;
}
/** @private */
SR_PRIV int sr_info(const char *format, ...)
{
int ret;
......@@ -238,6 +250,7 @@ SR_PRIV int sr_info(const char *format, ...)
return ret;
}
/** @private */
SR_PRIV int sr_warn(const char *format, ...)
{
int ret;
......@@ -250,6 +263,7 @@ SR_PRIV int sr_warn(const char *format, ...)
return ret;
}
/** @private */
SR_PRIV int sr_err(const char *format, ...)
{
int ret;
......
......@@ -20,6 +20,7 @@
#include "libsigrok.h"
#include "libsigrok-internal.h"
/** @cond PRIVATE */
extern SR_PRIV struct sr_output_format output_text_bits;
extern SR_PRIV struct sr_output_format output_text_hex;
extern SR_PRIV struct sr_output_format output_text_ascii;
......@@ -32,6 +33,7 @@ extern SR_PRIV struct sr_output_format output_csv;
extern SR_PRIV struct sr_output_format output_float;
extern SR_PRIV struct sr_output_format output_analog;
/* extern SR_PRIV struct sr_output_format output_analog_gnuplot; */
/* @endcond */
static struct sr_output_format *output_module_list[] = {
&output_text_bits,
......
......@@ -412,6 +412,8 @@ static void datafeed_dump(struct sr_datafeed_packet *packet)
* @param packet The datafeed packet to send to the session bus.
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
*
* @private
*/
SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi,
struct sr_datafeed_packet *packet)
......
......@@ -27,7 +27,9 @@
#include "libsigrok-internal.h"
/* size of payloads sent across the session bus */
/** @cond PRIVATE */
#define CHUNKSIZE (512 * 1024)
/** @endcond */
struct session_vdev {
char *sessionfile;
......@@ -269,6 +271,7 @@ static int hw_dev_acquisition_start(const struct sr_dev_inst *sdi,
return SR_OK;
}
/** @private */
SR_PRIV struct sr_dev_driver session_driver = {
.name = "session",
.longname = "Session-emulating driver",
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment