Index: doc/Doxyfile
===================================================================
--- doc/Doxyfile	(revision 16)
+++ doc/Doxyfile	(revision 17)
@@ -656,5 +656,5 @@
 # with spaces.
 
-INPUT                  = ../src/hu/varadiistvan/scpl \
+INPUT                  = overview.dox ../src/hu/varadiistvan/scpl \
                          ../src/hu/varadiistvan/scpl/io
 
Index: doc/overview.dox
===================================================================
--- doc/overview.dox	(revision 17)
+++ doc/overview.dox	(revision 17)
@@ -0,0 +1,142 @@
+/*! \mainpage Very Simple Cross-Platform Library Documentation
+ *
+ * \section intro Introduction
+ *
+ * VSCPL is a simple library containing some useful classes related to
+ * thread handling and I/O for POSIX and Windows systems. It is
+ * intended to be extended eventually, but has been written chiefly
+ * for the X-Plane Remote Access plugin and its client libraries,
+ * which is reflected by the rather minimal functionality.
+ *
+ * To avoid namespace clashes, the classes of the library are put in
+ * the \c hu::varadiistvan::scpl namespace or children of it.
+ *
+ * \subsection threading Threading
+ *
+ * The usual \ref hu::varadiistvan::scpl::Thread "thread" class and
+ * some threading primitives are provided:
+ * \ref hu::varadiistvan::scpl::Mutex "mutexes" and
+ * \ref hu::varadiistvan::scpl::CondVar "conditional variables".
+ *
+ * \subsection io Input/Output
+ *
+ * The I/O parts are somewhat generic, but currently support
+ * communication via so-called "local" sockets, which are Unix sockets
+ * on POSIX and named pipes on Windows. Of course, a common interface
+ * is provided, so the actual details are hidden.
+ *
+ * Input/output handling is based on the notion of a thread waiting
+ * for one or more I/O events and then handling them. For this purpose
+ * an instance of the \ref hu::varadiistvan::scpl::io::Waiter class
+ * should be created and then this instance should be passed to the
+ * instances of other classes. Waiting can be accomplished by calling
+ * its \ref hu::varadiistvan::scpl::io::Waiter::wait "wait" function
+ * and optionally passing a timeout.
+ *
+ * A local server socket can be created by instantiation the
+ * \ref hu::varadiistvan::scpl::io::LocalServerSocket class. Besides
+ * the waiter, it is given a name. It is ensured that if several users
+ * of the computer run programs using the same name, each will see
+ * their own socket.
+ *
+ * A server socket needs to accept incoming connections. For this
+ * purpose and \ref hu::varadiistvan::scpl::io::LocalAcceptor
+ * "acceptor" instance is used, which can be acquired by calling the
+ * \ref hu::varadiistvan::scpl::io::LocalServerSocket::getAcceptor
+ * "getAcceptor" function. To check, if there is an incoming
+ * connection, call the acceptor's
+ * \ref hu::varadiistvan::scpl::io::LocalAcceptor::accept "accept"
+ * function. It returns immediately with a boolean telling whether
+ * there is a connection. If so, you should call the
+ * \ref hu::varadiistvan::scpl::io::LocalAcceptor::getSocket
+ * "getSocket" function to get the socket representing the connection.
+ * If there is no incoming connection, you can wait for one using the
+ * waiter. Note, that
+ * \ref hu::varadiistvan::scpl::io::LocalAcceptor::accept "accept"
+ * should be called once unsuccessfully before trying to wait,
+ * otherwise it is not guaranteed that waiting will finish if a new
+ * connection comes in.
+ *
+ * \c LocalAcceptor is a subclass of
+ * \ref hu::varadiistvan::scpl::io::Failable "Failable", which can be
+ * used to check if some error occured. If \c accept returns \c false,
+ * it should be check if the failure of accepting is due to an error,
+ * or is caused simply by no client wanting to connect.
+ *
+ * A local client socket is created by instantiation
+ * \ref hu::varadiistvan::scpl::io::LocalClientSocket. It receives the
+ * same name as the server socket to which we want to
+ * connect. Similarly to accepting a connection on a server socket,
+ * the client socket's
+ * \ref hu::varadiistvan::scpl::io::LocalClientSocket::getConnector
+ * "getConnector" should be called to retrieve a
+ * \ref hu::varadiistvan::scpl::io::LocalConnector "LocalConnector"
+ * instance. Its
+ * \ref hu::varadiistvan::scpl::io::LocalConnector::connect "connect"
+ * member function should be called to initiate the connection. If it
+ * returns \c true, the connection has succeeded. Otherwise one can
+ * wait using the socket's waiter for the connection to succeed. If
+ * waiting finishes, \c connect can be called again to check, if the
+ * connection has been established. In case of a \c false return
+ * value, the error condition should be checked here as well.
+ *
+ * Once the connection has been established, the actual communication
+ * can begin. Both \c LocalSocket and \c LocalClientSocket are
+ * subclasses of
+ * \ref hu::varadiistvan::scpl::io::BufferedStream "BufferedStream".
+ * It can be used to acquire an instance of
+ * \ref hu::varadiistvan::scpl::io::ReadingBuffer "ReadingBuffer" for
+ * reading, and an instance of
+ * \ref hu::varadiistvan::scpl::io::WritingBuffer "WritingBuffer" for
+ * writing.
+ *
+ * To read, call the
+ * \ref hu::varadiistvan::scpl::io::ReadingBuffer::read "read"
+ * function. It returns \c true, if reading has succeeded, \c false
+ * otherwise which may indicate an error condition or simply the fact
+ * that nothing has been received yet, in which case the program can
+ * wait using the \c Waiter. If data has been read, it can be accessed
+ * by the buffer's methods inherited from
+ * \ref hu::varadiistvan::scpl::io::Buffer "Buffer". Before reading
+ * again, the buffer's
+ * \ref hu::varadiistvan::scpl::io::Buffer::reset "reset" function
+ * should be called, otherwise \c read just returns \c true and
+ * nothing happens.
+ *
+ * To write, put data into the writing buffer and call its
+ * \ref hu::varadiistvan::scpl::io::WritingBuffer::write "write"
+ * function. If all data in the buffer could be written, it returns
+ * \c true, otherwise \c false, which, again, might indicate error,
+ * but also the fact that not all data could be written. In this case,
+ * the program can wait, and then retry writing again, and do this
+ * until finally \c write returns \c true. If writing succeeds, the
+ * buffer is reset automatically, and one can put new data into it.
+ *
+ * The facilities described above provide for asynchronous,
+ * event-based stream handling, which is perfect for programs or
+ * threads that should work with several streams, timeouts and
+ * possibly other events simultaneously. This is, however, not always
+ * the case. It might very well be that one thread is dedicated to
+ * just deal with one stream only or at least with one stream at a
+ * time. In such a case this hocus-pocus with always (re)trying
+ * operations and waiting can be very cumbersome. It would be much
+ * better to just call a function to read or write, which would return
+ * only, if the requested operation has completed.
+ *
+ * This is provided by the
+ * \ref hu::varadiistvan::scpl::io::BlockingStream class. Its
+ * constructor receives and instance of \c BufferedStream, and it
+ * provides blocking read, write and flushing operations. It also has
+ * a \ref hu::varadiistvan::scpl::io::BlockingStream::interrupt "interrupt"
+ * function, which can be called from another thread. If the stream is
+ * blocking on an operation, that operation will then return with \c
+ * false, and the interrupted condition can the be
+ * \ref hu::varadiistvan::scpl::io::BlockingStream::isInterrupted
+ * "checked".
+ *
+ * \c BlockingStream has a subclass called
+ * \ref hu::varadiistvan::scpl::io::DataStream "DataStream", which can
+ * be used to read and write values of the primitive data types. The
+ * endianness is that of the  processor, i.e. no conversion is made to
+ * a common one.
+ */
