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

diff --git a/controller.c b/controller.c
index 2bc0a8c61866822e01253d5148fd419e5871c79a..05dbf3eb8bbfea6609d24cc446fc87303c249ee1 100644 (file)
--- 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 841e4321180a45ff3d79b6c512bdc54eb81e8e3b..e3f847d205ea7db534ad9e93b2372fb7bf057774 100644 (file)
--- 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 5693abfaed307ed918d793770f361f905507a7aa..d8e98ba2b692f99f6e272a45b4546f552076194c 100644 (file)
--- 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 a16154e55f703fb988e496ef5704376f9dd1a474..bdd7563d7c777987150432b59a548662ed4d0596 100644 (file)
--- 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 f66c244cf9ab046561f2f8d9af942d2b93780176..c1fbb0de269a7039a1d5b7fac9338556f181950a 100644 (file)
--- 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 5e499f4a8c9ee4cfa4feb1f4e6c4c6abd062c39c..bb4ef3d262b09b60bcca6617d86514b63ed20d5d 100644 (file)
--- 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 =