From: Bert Vermeulen <redacted>
Date: Sun, 12 Feb 2012 13:55:20 +0000 (+0100)
Subject: srd: last public/private fix, and docs for all publis functions.
X-Git-Tag: libsigrokdecode-0.1.0~48
X-Git-Url: https://sigrok.org/gitaction?a=commitdiff_plain;h=582c8473ffd456dfb0796974ef2c0b1b78de38a8;p=libsigrokdecode.git

srd: last public/private fix, and docs for all publis functions.
---

diff --git a/controller.c b/controller.c
index 2bc0a8c..05dbf3e 100644
--- a/controller.c
+++ b/controller.c
@@ -471,6 +471,14 @@ SRD_API struct srd_decoder_inst *srd_inst_new(const char *decoder_id,
 	return di;
 }
 
+/**
+ * Stack a decoder instance on top of another.
+ *
+ * @param di_from The instance to move.
+ * @param di_to The instance on top of which di_from will be stacked.
+ *
+ * @return SRD_OK upon success, a (negative) error code otherwise.
+ */
 SRD_API int srd_inst_stack(struct srd_decoder_inst *di_from,
 			       struct srd_decoder_inst *di_to)
 {
@@ -684,6 +692,17 @@ SRD_PRIV void srd_inst_free_all(GSList *stack)
 	}
 }
 
+/**
+ * Start a decoding session.
+ *
+ * Decoders, instances and stack must have been prepared beforehand.
+ *
+ * @param num_probes The number of probes which the incoming feed will contain.
+ * @param unitsize The number of bytes per sample in the incoming feed.
+ * @param The samplerate of the incoming feed.
+ *
+ * @return SRD_OK upon success, a (negative) error code otherwise.
+ */
 SRD_API int srd_session_start(int num_probes, int unitsize, uint64_t samplerate)
 {
 	PyObject *args;
@@ -717,8 +736,16 @@ SRD_API int srd_session_start(int num_probes, int unitsize, uint64_t samplerate)
 	return ret;
 }
 
-/* Feed logic samples to decoder session. */
-SRD_API int srd_session_feed(uint64_t start_samplenum, uint8_t * inbuf,
+/**
+ * Feed a chunk of logic sample data to a running decoder session.
+ *
+ * @param start_samplenum The sample number of the first sample in this chunk.
+ * @param inbuf Pointer to sample data.
+ * @param inbuf Length in bytes of the buffer.
+ *
+ * @return SRD_OK upon success, a (negative) error code otherwise.
+ */
+SRD_API int srd_session_feed(uint64_t start_samplenum, uint8_t *inbuf,
 			     uint64_t inbuflen)
 {
 	GSList *d;
@@ -737,6 +764,18 @@ SRD_API int srd_session_feed(uint64_t start_samplenum, uint8_t * inbuf,
 	return SRD_OK;
 }
 
+/**
+ * Register a decoder output callback function.
+ *
+ * The function will be called when a protocol decoder sends output back
+ * to the PD controller (except for Python objects, which only go up the
+ * stack).
+ *
+ * @param output_type The output type this callback will receive. Only one
+ * callback per output type can be registered.
+ * @param cb The function to call.
+ * @param user_data Unused.
+ */
 SRD_API int srd_register_callback(int output_type,
 				  srd_pd_output_callback_t cb, void *user_data)
 {
@@ -757,7 +796,7 @@ SRD_API int srd_register_callback(int output_type,
 	return SRD_OK;
 }
 
-SRD_API void *srd_find_callback(int output_type)
+SRD_PRIV void *srd_find_callback(int output_type)
 {
 	GSList *l;
 	struct srd_pd_callback *pd_cb;
diff --git a/decoder.c b/decoder.c
index 841e432..e3f847d 100644
--- a/decoder.c
+++ b/decoder.c
@@ -45,6 +45,7 @@ SRD_API GSList *srd_list_decoders(void)
  * Get the decoder with the specified ID.
  *
  * @param id The ID string of the decoder to return.
+ *
  * @return The decoder with the specified ID, or NULL if not found.
  */
 SRD_API struct srd_decoder *srd_get_decoder_by_id(const char *id)
@@ -281,6 +282,14 @@ err_out:
 	return ret;
 }
 
+/**
+ * Return a protocol decoder's docstring.
+ *
+ * @param dec The loaded protocol decoder.
+ *
+ * @return A newly allocated buffer containing the docstring. The caller should
+ * free this after use.
+ */
 SRD_API char *srd_decoder_doc(struct srd_decoder *dec)
 {
 	PyObject *py_str;
@@ -362,6 +371,11 @@ SRD_API int srd_unload_decoder(struct srd_decoder *dec)
 	return SRD_OK;
 }
 
+/**
+ * Load all protocol decoders libsigrokdecode knows about.
+ *
+ * @return SRD_OK upon success, a (negative) error code otherwise.
+ */
 SRD_API int srd_load_all_decoders(void)
 {
 	GDir *dir;
@@ -390,7 +404,9 @@ SRD_API int srd_load_all_decoders(void)
 }
 
 /**
- * TODO
+ * Unload all loaded protocol decoders.
+ *
+ * @return SRD_OK upon success, a (negative) error code otherwise.
  */
 SRD_API int srd_unload_all_decoders(void)
 {
diff --git a/log.c b/log.c
index 5693abf..d8e98ba 100644
--- a/log.c
+++ b/log.c
@@ -57,6 +57,7 @@ static char srd_log_domain[LOGDOMAIN_MAXLEN + 1] = LOGDOMAIN_DEFAULT;
  *
  * @param loglevel The loglevel to set (SRD_LOG_NONE, SRD_LOG_ERR,
  *                 SRD_LOG_WARN, SRD_LOG_INFO, SRD_LOG_DBG, or SRD_LOG_SPEW).
+ *
  * @return SRD_OK upon success, SRD_ERR_ARG upon invalid loglevel.
  */
 SRD_API int srd_log_loglevel_set(int loglevel)
@@ -94,6 +95,7 @@ SRD_API int srd_log_loglevel_get(void)
  *                  In order to not use a logdomain, pass an empty string.
  *                  The function makes its own copy of the input string, i.e.
  *                  the caller does not need to keep it around.
+ *
  * @return SRD_OK upon success, SRD_ERR_ARG upon invalid logdomain.
  */
 SRD_API int srd_log_logdomain_set(const char *logdomain)
@@ -134,6 +136,7 @@ SRD_API char *srd_log_logdomain_get(void)
  *                  and is never used or interpreted in any way. The pointer
  *                  is allowed to be NULL if the caller doesn't need/want to
  *                  pass any data.
+ *
  * @return SRD_OK upon success, SRD_ERR_ARG upon invalid arguments.
  */
 SRD_API int srd_log_handler_set(srd_log_handler_t handler, void *user_data)
@@ -156,7 +159,7 @@ SRD_API int srd_log_handler_set(srd_log_handler_t handler, void *user_data)
  *
  * Additionally, the internal 'srd_log_handler_data' pointer is set to NULL.
  *
- * @return SRD_OK upon success, a negative error code otherwise.
+ * @return SRD_OK upon success, a (negative) error code otherwise.
  */
 SRD_API int srd_log_handler_set_default(void)
 {
diff --git a/sigrokdecode-internal.h b/sigrokdecode-internal.h
index a16154e..bdd7563 100644
--- a/sigrokdecode-internal.h
+++ b/sigrokdecode-internal.h
@@ -46,6 +46,9 @@ SRD_PRIV void srd_inst_free_all(GSList *stack);
 SRD_PRIV int pd_add(struct srd_decoder_inst *di, int output_type,
 		    char *output_id);
 
+/*--- decoder.c -------------------------------------------------------------*/
+SRD_PRIV void *srd_find_callback(int output_type);
+
 /*--- exception.c -----------------------------------------------------------*/
 
 SRD_PRIV void catch_exception(const char *format, ...);
diff --git a/sigrokdecode.h b/sigrokdecode.h
index f66c244..c1fbb0d 100644
--- a/sigrokdecode.h
+++ b/sigrokdecode.h
@@ -217,7 +217,6 @@ SRD_API int srd_session_feed(uint64_t start_samplenum, uint8_t *inbuf,
 SRD_API struct srd_decoder_inst *get_di_by_decobject(void *decobject);
 SRD_API int srd_register_callback(int output_type,
 				  srd_pd_output_callback_t cb, void *user_data);
-SRD_API void *srd_find_callback(int output_type);
 
 /*--- decoder.c -------------------------------------------------------------*/
 
diff --git a/type_logic.c b/type_logic.c
index 5e499f4..bb4ef3d 100644
--- a/type_logic.c
+++ b/type_logic.c
@@ -49,8 +49,7 @@ static PyObject *srd_logic_iternext(PyObject *self)
 	       logic->inbuf + logic->itercnt * logic->di->data_unitsize,
 	       logic->di->data_unitsize);
 	for (i = 0; i < logic->di->dec_num_probes; i++)
-		probe_samples[i] =
-		    sample & (1 << logic->di->dec_probemap[i]) ? 1 : 0;
+		probe_samples[i] = sample & (1 << logic->di->dec_probemap[i]) ? 1 : 0;
 
 	/* Prepare the next samplenum/sample list in this iteration. */
 	py_samplenum =