diff --git a/src/mqtt/async_client.h b/src/mqtt/async_client.h
index 8799889..d0c7c12 100644
--- a/src/mqtt/async_client.h
+++ b/src/mqtt/async_client.h
@@ -71,8 +71,38 @@ namespace mqtt {
 /////////////////////////////////////////////////////////////////////////////
 
 /**
- * Lightweight client for talking to an MQTT server using non-blocking
+ * Client for talking to an MQTT server using non-blocking
  * methods that allow an operation to run in the background.
+ *
+ * The location of the server is specified as a URI string with the
+ * following schemas supported to specify the type and security used for the
+ * connection:
+ * @li @em "mqtt://" - A standard (insecure) connection over TCP. (Also,
+ * "tcp://")
+ * @li @em "mqtts://" - A secure connection using SSL/TLS sockets. (Also
+ * "ssl://")
+ * @li @em "ws://" - A standard (insecure) WebSocket connection.
+ * @li @em "wss:// - A secure websocket connection using SSL/TLS.
+ *
+ * The secure connection types assume that the library was built with
+ * OpenSSL support, otherwise requesting a secure conection will result in
+ * an error.
+ *
+ * The communication methods of this class - `connect()`, `publish()`,
+ * `subscribe()`, etc. - are all asynchronous. They create the request for
+ * the server, but return imediately, before a response is received back
+ * from the server.
+ *
+ * These methods return a `Token` to the caller which is akin to a C++
+ * std::future. The caller can keep the Token, then use it later to block
+ * until the asynchronous operation is complete and retrieve the result of
+ * the operation, including any response from the server.
+ *
+ * Alternately, the application can choose to set callbacks to be fired when
+ * each operation completes. This can be used to create an event-driven
+ * architecture, but is more complex in that it forces the user to avoid any
+ * blocking operations and manually handle thread synchronization (since
+ * the callbacks run in a separate thread managed by the library).
  */
 class async_client : public virtual iasync_client
 {
diff --git a/src/mqtt/connect_options.h b/src/mqtt/connect_options.h
index c8bd706..f7dc3d9 100644
--- a/src/mqtt/connect_options.h
+++ b/src/mqtt/connect_options.h
@@ -470,6 +470,12 @@ public:
 	  *   @li MQTTVERSION_3_1 (3) = only try version 3.1
 	  *   @li MQTTVERSION_3_1_1 (4) = only try version 3.1.1
 	  *   @li MQTTVERSION_5 (5) = only try version 5
+	  *
+	  * @deprecated It is preferable to create the options for the desired
+	  * version rather than using this function to change the version after
+	  * some parameters have already been set. If you do use this function,
+	  * call it before setting any other version-specific options. @sa
+	  * connect_options::v5()
 	  */
 	void set_mqtt_version(int mqttVersion);
 	/**
@@ -668,6 +674,9 @@ public:
 	using self = connect_options_builder;
 	/**
 	 * Default constructor.
+	 *
+	 * @param ver The MQTT version for the connection. Defaults to the most
+	 *  		  recent v3 supported by the server.
 	 */
 	explicit connect_options_builder(int ver=MQTTVERSION_DEFAULT) : opts_(ver) {}
 	/**
@@ -851,6 +860,12 @@ public:
 	  *   @li MQTTVERSION_3_1 (3) = only try version 3.1
 	  *   @li MQTTVERSION_3_1_1 (4) = only try version 3.1.1
 	  *   @li MQTTVERSION_5 (5) = only try version 5
+	  *
+	  * @deprecated It is preferable to create the options builder for the
+	  * desired version rather than using this function to change the
+	  * version after some parameters have already been set. If you do use
+	  * this function, call it before setting any other version-specific
+	  * options. @sa connect_options_builder::v5()
 	  */
 	auto mqtt_version(int ver) -> self& {
 		opts_.set_mqtt_version(ver);