Doxygen: Initial groups and topic short descriptions.

[libsigrokdecode.git] / controller.c

diff --git a/controller.c b/controller.c
index c265ae7fe0d305af9cd4cb2a2b307eff1b091123..e35b8be2a987facf8c7d4bcc45c3cd5bfd4568a3 100644 (file)
--- a/controller.c
+++ b/controller.c
@@ -25,12 +25,75 @@
 #include <inttypes.h>
 #include <stdlib.h>
 
+/**
+ * @mainpage libsigrokdecode API
+ *
+ * @section sec_intro Introduction
+ *
+ * The <a href="http://sigrok.org">sigrok</a> project aims at creating a
+ * portable, cross-platform, Free/Libre/Open-Source signal analysis software
+ * suite that supports various device types (such as logic analyzers,
+ * oscilloscopes, multimeters, and more).
+ *
+ * <a href="http://sigrok.org/wiki/Libsigrokdecode">libsigrokdecode</a> is a
+ * shared library written in C which provides the basic API for (streaming)
+ * protocol decoding functionality.
+ *
+ * The <a href="http://sigrok.org/wiki/Protocol_decoders">protocol decoders</a>
+ * are written in Python (>= 3.0).
+ *
+ * @section sec_api API reference
+ *
+ * See the "Modules" page for an introduction to various libsigrokdecode
+ * related topics and the detailed API documentation of the respective
+ * functions.
+ *
+ * You can also browse the API documentation by file, or review all
+ * data structures.
+ *
+ * @section sec_mailinglists Mailing lists
+ *
+ * There are two mailing lists for sigrok/libsigrokdecode: <a href="https://lists.sourceforge.net/lists/listinfo/sigrok-devel">sigrok-devel</a> and <a href="https://lists.sourceforge.net/lists/listinfo/sigrok-commits">sigrok-commits</a>.
+ *
+ * @section sec_irc IRC
+ *
+ * You can find the sigrok developers in the
+ * <a href="irc://chat.freenode.net/sigrok">\#sigrok</a>
+ * IRC channel on Freenode.
+ *
+ * @section sec_website Website
+ *
+ * <a href="http://sigrok.org/wiki/Libsigrokdecode">sigrok.org/wiki/Libsigrokdecode</a>
+ */
+
+/**
+ * @file
+ *
+ * Initializing and shutting down libsigrokdecode.
+ */
+
+/**
+ * @defgroup grp_init Initialization
+ *
+ * Initializing and shutting down libsigrokdecode.
+ *
+ * Before using any of the libsigrokdecode functionality, srd_init() must
+ * be called to initialize the library.
+ *
+ * When libsigrokdecode functionality is no longer needed, srd_exit() should
+ * be called.
+ *
+ * @{
+ */
+
 /* List of decoder instances. */
 static GSList *di_list = NULL;
 
 /* List of frontend callbacks to receive decoder output. */
 static GSList *callbacks = NULL;
 
+/** @cond PRIVATE */
+
 /* decoder.c */
 extern SRD_PRIV GSList *pd_list;
 
@@ -41,6 +104,8 @@ extern PyMODINIT_FUNC PyInit_sigrokdecode(void);
 /* type_logic.c */
 extern SRD_PRIV PyTypeObject srd_logic_type;
 
+/** @endcond */
+
 /**
  * Initialize libsigrokdecode.
  *
@@ -144,6 +209,8 @@ SRD_API int srd_exit(void)
  *             be added to the Python sys.path, or NULL.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @private
  */
 SRD_PRIV int srd_decoder_searchpath_add(const char *path)
 {
@@ -198,6 +265,16 @@ SRD_PRIV int srd_decoder_searchpath_add(const char *path)
        return SRD_OK;
 }
 
+/** @} */
+
+/**
+ * @defgroup grp_instances Decoder instances
+ *
+ * Decoder instance handling.
+ *
+ * @{
+ */
+
 /**
  * Set one or more options in a decoder instance.
  *
@@ -558,6 +635,8 @@ SRD_API struct srd_decoder_inst *srd_inst_find_by_id(const char *inst_id)
  * @param obj The Python class instantiation.
  *
  * @return Pointer to struct srd_decoder_inst, or NULL if not found.
+ *
+ * @private
  */
 SRD_PRIV struct srd_decoder_inst *srd_inst_find_by_obj(const GSList *stack,
                                                       const PyObject *obj)
@@ -578,6 +657,7 @@ SRD_PRIV struct srd_decoder_inst *srd_inst_find_by_obj(const GSList *stack,
        return di;
 }
 
+/** @private */
 SRD_PRIV int srd_inst_start(struct srd_decoder_inst *di, PyObject *args)
 {
        PyObject *py_name, *py_res;
@@ -627,6 +707,8 @@ SRD_PRIV int srd_inst_start(struct srd_decoder_inst *di, PyObject *args)
  * @param inbuflen Length of the buffer. Must be > 0.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @private
  */
 SRD_PRIV int srd_inst_decode(uint64_t start_samplenum,
                             const struct srd_decoder_inst *di,
@@ -681,6 +763,7 @@ SRD_PRIV int srd_inst_decode(uint64_t start_samplenum,
        return SRD_OK;
 }
 
+/** @private */
 SRD_PRIV void srd_inst_free(struct srd_decoder_inst *di)
 {
        GSList *l;
@@ -700,6 +783,7 @@ SRD_PRIV void srd_inst_free(struct srd_decoder_inst *di)
        g_slist_free(di->pd_output);
 }
 
+/** @private */
 SRD_PRIV void srd_inst_free_all(GSList *stack)
 {
        GSList *l;
@@ -718,6 +802,16 @@ SRD_PRIV void srd_inst_free_all(GSList *stack)
        }
 }
 
+/** @} */
+
+/**
+ * @defgroup grp_session Session handling
+ *
+ * Starting and handling decoding sessions.
+ *
+ * @{
+ */
+
 /**
  * Start a decoding session.
  *
@@ -825,6 +919,7 @@ SRD_API int srd_pd_output_callback_add(int output_type,
        return SRD_OK;
 }
 
+/** @private */
 SRD_PRIV void *srd_pd_output_callback_find(int output_type)
 {
        GSList *l;
@@ -844,6 +939,7 @@ SRD_PRIV void *srd_pd_output_callback_find(int output_type)
 }
 
 /* This is the backend function to Python sigrokdecode.add() call. */
+/** @private */
 SRD_PRIV int srd_inst_pd_output_add(struct srd_decoder_inst *di,
                                    int output_type, const char *proto_id)
 {
@@ -866,3 +962,5 @@ SRD_PRIV int srd_inst_pd_output_add(struct srd_decoder_inst *di,
 
        return pdo->pdo_id;
 }
+
+/** @} */