From: Uwe Hermann <redacted>
Date: Fri, 19 Oct 2012 08:07:22 +0000 (+0200)
Subject: Doxygen: Mark non-public stuff for exclusion.
X-Git-Tag: dsupstream~642
X-Git-Url: http://sigrok.org/gitweb/?p=libsigrok.git;a=commitdiff_plain;h=b4bd70889f3009f5d836a9bf701725a6aceac039

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 cd7e2655..d89f4a32 100644
--- 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 84d3d663..d5ad7b2b 100644
--- 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 3b1718d3..33d716da 100644
--- 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 06eb5117..f39dd6d5 100644
--- 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 cc680473..8cfcf53e 100644
--- 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 cb5826b2..b8f4f642 100644
--- 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 828c2d34..0c57a87b 100644
--- 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 6ba80428..e73411d5 100644
--- 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",