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.

diff --git a/HACKING b/HACKING
index cd7e26556d010ec6034e2c45fcecf9c2f79ca9f7..d89f4a32b8ec1a70a8987e1c2021f8c3a57dd322 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -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
 -------------------

diff --git a/device.c b/device.c
index 84d3d663dd6ff459589d844cd70cd40cd6776587..d5ad7b2b4b7b9763468edc853d509c8223cae521 100644 (file)
--- a/device.c
+++ b/device.c
@@ -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);

diff --git a/hwdriver.c b/hwdriver.c
index 3b1718d31adc00bf1be7f7539440582b509ce5cc..33d716da552c1debb92a1d3a3f583504e489afb9 100644 (file)
--- a/hwdriver.c
+++ b/hwdriver.c
@@ -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)
 {

diff --git a/input/input.c b/input/input.c
index 06eb511767cbe4d5e3e00ac3dc79c0c731e8fc54..f39dd6d5379a43214dffc9439bd45874b9297761 100644 (file)
--- a/input/input.c
+++ b/input/input.c
@@ -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,

diff --git a/log.c b/log.c
index cc680473aa6d112b7db8abbaa077028e2d5ffc82..8cfcf53efda2c94133e0f19dbc30a62ab9589f08 100644 (file)
--- a/log.c
+++ b/log.c
@@ -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;

diff --git a/output/output.c b/output/output.c
index cb5826b2efa74f409c006bb3a804fdf4bd3cc933..b8f4f64265963ad886d13f9b0724a7363b2d5de9 100644 (file)
--- a/output/output.c
+++ b/output/output.c
@@ -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,

diff --git a/session.c b/session.c
index 828c2d346bfadc3d9ec02ec459d9ea4ba24df013..0c57a87ba3a6573e73b00c24c173deb84a830b27 100644 (file)
--- a/session.c
+++ b/session.c
@@ -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)

diff --git a/session_driver.c b/session_driver.c
index 6ba804285b5d0ff8b2815c062cb879a823baad74..e73411d521fa0fe74118e4c5df7753367410eec7 100644 (file)
--- a/session_driver.c
+++ b/session_driver.c
@@ -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",