From: Uwe Hermann <redacted>
Date: Mon, 22 Oct 2012 00:32:53 +0000 (+0200)
Subject: Doxygen: Explain init/shutdown, add small example.
X-Git-Tag: dsupstream~632
X-Git-Url: https://sigrok.org/gitaction?a=commitdiff_plain;h=afe2f28e65f3c3d9b510f101d6cd76c59794cd17;p=libsigrok.git

Doxygen: Explain init/shutdown, add small example.
---

diff --git a/backend.c b/backend.c
index 9f0f119f..389df253 100644
--- a/backend.c
+++ b/backend.c
@@ -74,6 +74,42 @@
  *
  * Initializing and shutting down libsigrok.
  *
+ * Before using any of the libsigrok functionality, sr_init() must
+ * be called to initialize the library, which will return a struct sr_context
+ * when the initialization was successful.
+ *
+ * When libsigrok functionality is no longer needed, sr_exit() should be
+ * called, which will (among other things) free the struct sr_context.
+ *
+ * Example for a minimal program using libsigrok:
+ *
+ * @code{.c}
+ *   #include <stdio.h>
+ *   #include <libsigrok/libsigrok.h>
+ *
+ *   int main(int argc, char **argv)
+ *   {
+ *   	int ret;
+ *   	struct sr_context *sr_ctx;
+ *
+ *   	if ((ret = sr_init(&sr_ctx)) != SR_OK) {
+ *   		printf("Error initializing libsigrok (%s): %s.",
+ *   		       sr_strerror_name(ret), sr_strerror(ret));
+ *   		return 1;
+ *   	}
+ *
+ *   	// Use libsigrok functions here...
+ *
+ *   	if ((ret = sr_exit(sr_ctx)) != SR_OK) {
+ *   		printf("Error shutting down libsigrok (%s): %s.",
+ *   		       sr_strerror_name(ret), sr_strerror(ret));
+ *   		return 1;
+ *   	}
+ *
+ *   	return 0;
+ *   }
+ * @endcode
+ *
  * @{
  */