Add information about thread safety.

asio/include/asio/basic_demuxer.hpp

@@ -30,10 +30,22 @@
 
 namespace asio {
 
-/// The basic_demuxer class template provides the core event demultiplexing
-/// functionality for users of the asynchronous I/O objects, such as
-/// asio::stream_socket, and also to developers of custom asynchronous
-/// services. Most applications will use the asio::demuxer typedef.
+/// Provides core event demultiplexing functionality.
+/**
+ * The basic_demuxer class template provides the core event demultiplexing
+ * functionality for users of the asynchronous I/O objects, including
+ * asio::stream_socket, asio::dgram_socket, asio::socket_acceptor,
+ * asio::socket_connector and asio::timer. The basic_demuxer class template
+ * also includes facilities intended for developers of custom asynchronous
+ * services.
+ *
+ * Most applications will use the asio::demuxer typedef.
+ *
+ * @par Thread Safety:
+ * @e Distinct @e objects: Safe.@n
+ * @e Shared @e objects: Safe, with the exception that calling reset()
+ * while there are unfinished run() calls results in undefined behaviour.
+ */
 template <typename Demuxer_Service>
 class basic_demuxer
   : private boost::noncopyable

asio/include/asio/basic_dgram_socket.hpp

@@ -26,9 +26,17 @@
 
 namespace asio {
 
-/// The basic_dgram_socket class template provides asynchronous and blocking
-/// datagram-oriented socket functionality. Most applications will use the
-/// asio::dgram_socket typedef.
+/// Provides datagram-oriented socket functionality.
+/**
+ * The basic_dgram_socket class template provides asynchronous and blocking
+ * datagram-oriented socket functionality.
+ *
+ * Most applications will use the asio::dgram_socket typedef.
+ *
+ * @par Thread Safety:
+ * @e Distinct @e objects: Safe.@n
+ * @e Shared @e objects: Unsafe.
+ */
 template <typename Service>
 class basic_dgram_socket
   : private boost::noncopyable

asio/include/asio/basic_locking_dispatcher.hpp

@@ -25,10 +25,18 @@
 
 namespace asio {
 
-/// The basic_locking_dispatcher class template provides the ability to post
-/// and dispatch handlers with the guarantee that none of those handlers will
-/// execute concurrently. Most applications will use the
-/// asio::locking_dispatcher typedef.
+/// Provides serialised handler execution.
+/**
+ * The basic_locking_dispatcher class template provides the ability to post
+ * and dispatch handlers with the guarantee that none of those handlers will
+ * execute concurrently.
+ *
+ * Most applications will use the asio::locking_dispatcher typedef.
+ *
+ * @par Thread Safety:
+ * @e Distinct @e objects: Safe.@n
+ * @e Shared @e objects: Safe.
+ */
 template <typename Service>
 class basic_locking_dispatcher
 {

asio/include/asio/basic_socket_acceptor.hpp

@@ -26,8 +26,17 @@
 
 namespace asio {
 
-/// The basic_socket_acceptor class template is used for accepting new socket
-/// connections. Most applications would use the asio::socket_acceptor typedef.
+/// Provides the ability to accept new connections.
+/**
+ * The basic_socket_acceptor class template is used for accepting new socket
+ * connections.
+ *
+ * Most applications would use the asio::socket_acceptor typedef.
+ *
+ * @par Thread Safety:
+ * @e Distinct @e objects: Safe.@n
+ * @e Shared @e objects: Unsafe.
+ */
 template <typename Service>
 class basic_socket_acceptor
   : private boost::noncopyable

asio/include/asio/basic_socket_connector.hpp

@@ -26,9 +26,17 @@
 
 namespace asio {
 
-/// The basic_socket_connector class template is used to connect a socket to a
-/// remote endpoint. Most applications will use the asio::socket_connector
-/// typedef.
+/// Provides the ability to make new connections.
+/**
+ * The basic_socket_connector class template is used to connect a socket to a
+ * remote endpoint.
+ *
+ * Most applications will use the asio::socket_connector typedef.
+ *
+ * @par Thread Safety:
+ * @e Distinct @e objects: Safe.@n
+ * @e Shared @e objects: Unsafe.
+ */
 template <typename Service>
 class basic_socket_connector
   : private boost::noncopyable

asio/include/asio/basic_stream_socket.hpp

@@ -26,9 +26,17 @@
 
 namespace asio {
 
-/// The basic_stream_socket class template provides asynchronous and blocking
-/// stream-oriented socket functionality. Most applications will use the
-/// asio::stream_socket typedef.
+/// Provides stream-oriented socket functionality.
+/**
+ * The basic_stream_socket class template provides asynchronous and blocking
+ * stream-oriented socket functionality.
+ *
+ * Most applications will use the asio::stream_socket typedef.
+ *
+ * @par Thread Safety:
+ * @e Distinct @e objects: Safe.@n
+ * @e Shared @e objects: Unsafe.
+ */
 template <typename Service>
 class basic_stream_socket
   : private boost::noncopyable

asio/include/asio/basic_timer.hpp

@@ -26,8 +26,17 @@
 
 namespace asio {
 
-/// The basic_timer class template provides asynchronous timer functionality.
-/// Most applications will use the asio::timer typedef.
+/// Provides waitable timer functionality.
+/**
+ * The basic_timer class template provides the ability to perform a blocking or
+ * asynchronous wait for a timer to expire..
+ *
+ * Most applications will use the asio::timer typedef.
+ *
+ * @par Thread Safety:
+ * @e Distinct @e objects: Safe.@n
+ * @e Shared @e objects: Unsafe.
+ */
 template <typename Service>
 class basic_timer
   : public timer_base,

asio/include/asio/thread.hpp

@@ -21,16 +21,22 @@
 
 namespace asio {
 
-/// The thread class provides a very simple abstraction for starting threads.
+/// A simple abstraction for starting threads.
 /**
  * The asio::thread class implements the smallest possible subset of the
  * functionality of boost::thread. It is intended to be used only for starting
  * a thread and waiting for it to exit. If more extensive threading
  * capabilities are required, you are strongly advised to use something else.
  *
+ * @par Thread Safety:
+ * @e Distinct @e objects: Safe.@n
+ * @e Shared @e objects: Unsafe.
+ *
+ * @par Example:
  * A typical use of asio::thread would be to launch a thread to run a demuxer's
  * event processing loop:
  *
+ * @par
  * @code asio::demuxer d;
  * // ...
  * asio::thread t(boost::bind(&asio::demuxer::run, &d));