From: Martin Ling <redacted>
Date: Wed, 27 May 2015 09:53:46 +0000 (+0100)
Subject: doc: Additional introductory text.
X-Git-Tag: libserialport-0.1.1~23
X-Git-Url: https://sigrok.org/gitweb/?p=libserialport.git;a=commitdiff_plain;h=49fd7b1bc249a122e4f27c5d383d7789eac61da3

doc: Additional introductory text.
---

diff --git a/libserialport.h.in b/libserialport.h.in
index 8fd548e..4369afa 100644
--- a/libserialport.h.in
+++ b/libserialport.h.in
@@ -58,8 +58,32 @@
  * For particular notes on porting existing code, see @ref Porting.
  *
  * The following subsections will help explain the principles of the API.
- * To jump directly into the detailed function documentation, see the
- * <a href="modules.html">categorised function lists</a>.
+ *
+ * Headers
+ * -------
+ *
+ * To use libserialport functions in your code, you should include the
+ * libserialport.h header, i.e. "#include <libserialport.h>".
+ *
+ * Namespace
+ * ---------
+ *
+ * All identifiers defined by the public libserialport headers use the prefix
+ * sp_ (for functions and data types) or SP_ (for macros and constants).
+ *
+ * Functions
+ * ---------
+ *
+ * The functions provided by the library are documented in detail in
+ * the following sections:
+ *
+ * - @ref Enumeration (obtaining a list of serial ports on the system)
+ * - @ref Ports (opening, closing and getting information about ports)
+ * - @ref Configuration (baud rate, parity, etc.)
+ * - @ref Signals (modem control lines, breaks, etc.)
+ * - @ref Data (reading and writing data, and buffer management)
+ * - @ref Waiting (waiting for ports to be ready, integrating with event loops)
+ * - @ref Errors (getting error and debugging information)
  *
  * Data structures
  * ---------------