From: Uwe Hermann <redacted>
Date: Wed, 23 Nov 2011 07:56:44 +0000 (+0100)
Subject: srd: Doxygen comments for srd_init() and srd_exit().
X-Git-Tag: libsigrokdecode-0.1.0~271
X-Git-Url: https://sigrok.org/gitaction?a=commitdiff_plain;h=c75080f0d84de5f2aa73472ad4d6cf32aaeba88e;p=libsigrokdecode.git

srd: Doxygen comments for srd_init() and srd_exit().
---

diff --git a/decode.c b/decode.c
index 396cde8..6c63fa7 100644
--- a/decode.c
+++ b/decode.c
@@ -77,7 +77,24 @@ static PyMethodDef EmbMethods[] = {
 /**
  * Initialize libsigrokdecode.
  *
+ * This initializes the Python interpreter, and creates and initializes
+ * a "sigrok" Python module with a single put() method.
+ *
+ * Then, it searches for sigrok protocol decoder files (*.py) in the
+ * "decoders" subdirectory of the the sigrok installation directory.
+ * All decoders that are found are loaded into memory and added to an
+ * internal list of decoders, which can be queried via srd_list_decoders().
+ *
+ * The caller is responsible for calling the clean-up function srd_exit(),
+ * which will properly shut down libsigrokdecode and free its allocated memory.
+ *
+ * Multiple calls to srd_init(), without calling srd_exit() inbetween,
+ * are not allowed.
+ *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *         Upon Python errors, return SRD_ERR_PYTHON. If the sigrok decoders
+ *         directory cannot be accessed, return SRD_ERR_DECODERS_DIR.
+ *         If not enough memory could be allocated, return SRD_ERR_MALLOC.
  */
 int srd_init(void)
 {
@@ -450,6 +467,13 @@ static int srd_unload_all_decoders(void)
 /**
  * Shutdown libsigrokdecode.
  *
+ * This frees all the memory allocated for protocol decoders and shuts down
+ * the Python interpreter.
+ *
+ * This function should only be called if there was a (successful!) invocation
+ * of srd_init() before. Calling this function multiple times in a row, without
+ * any successful srd_init() calls inbetween, is not allowed.
+ *
  * @return SRD_OK upon success, a (negative) error code otherwise.
  */
 int srd_exit(void)