doc: Provided channel is binary, not necessarily 8-bit.

[libserialport.git] / libserialport.h.in

diff --git a/libserialport.h.in b/libserialport.h.in
index 8fd548e18cbaa4dbde6c2e310810bceb01ab58ea..4f69643ef985a47c6d86e399f46c12a6b87d4b1c 100644 (file)
--- 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
  * ---------------
@@ -177,7 +201,7 @@
  * for dealing with serial devices at the OS level; this is exposed through the
  * termios API and dates to the days when serial terminals were common. If your
  * code relies on many of these facilities you will need to adapt it, because
- * libserialport provides only a raw 8-bit channel with no special handling.
+ * libserialport provides only a raw binary channel with no special handling.
  *
  * The second relates to blocking versus non-blocking I/O behaviour. In
  * Unix-like systems this is normally specified by setting the O_NONBLOCK