Add some notes to the documentation

src/docs/MainPage.dox

@@ -16,8 +16,9 @@ Its features are as follows:
  \li simple event loop interface (see section \ref eventloop)
  \li wrapper functions for adding and removing file descriptors (see section \ref fdevent)
  \li signal delivery through file descriptor (see section \ref signalfd)
- \li timer functions (TODO)
+ \li timer functions (TODO -- awaiting timerfd(2) from linux-2.6.25)
  \li safe inter-object actions (one object may free another at any time)
+ \li safe to call any library function from callbacks
  \li O(1) design to match that of \c epoll(7)
 
 See the page \ref libdesign for detailed information on the implementation.

src/docs/libdesign.dox

@@ -7,6 +7,15 @@
 
 /*! \page libdesign Library design
 
+\section libdesign_common Optimised for common use-case
+
+This library has been written with a common use-case in mind: non-blocking, event-driven,
+single-threaded applications which use finite state machines (or some similar mechanism). In
+particular, this has the following consequences:
+
+\li The \c epoll(7) file descriptor is hidden. It is marked close on exec.
+\li It is safe to call any library function from an event callback.
+
 \section libdesign_O1 O(1) design
 
 Like the \c epoll(7) facility, \a liblwevent is designed to be O(1): execution time does not scale