/*
* This file is part of the libserialport project.
*
- * Copyright (C) 2013 Martin Ling <martin-libserialport@earth.li>
+ * Copyright (C) 2013, 2015 Martin Ling <martin-libserialport@earth.li>
+ * Copyright (C) 2014 Uwe Hermann <uwe@hermann-uwe.de>
+ * Copyright (C) 2014 Aurelien Jacobs <aurel@gnuage.org>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as
* 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
* ---------------
* 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