diff --git a/README.md b/README.md
index 929b566..ec2b07f 100644
--- a/README.md
+++ b/README.md
@@ -53,7 +53,7 @@ require 'vendor/autoload.php';
## Usage ##
To use this API, you must create a new ``\GeoIP2\Webservice\Client``
-object with your ``userId`` and ``licenseKey``, then you call the method
+object with your ``$userId`` and ``$licenseKey``, then you call the method
corresponding to a specific end point, passing it the IP address you want to
look up.
diff --git a/src/GeoIP2/Webservice/Client.php b/src/GeoIP2/Webservice/Client.php
index 551bd97..7d22da0 100644
--- a/src/GeoIP2/Webservice/Client.php
+++ b/src/GeoIP2/Webservice/Client.php
@@ -29,6 +29,41 @@ use Guzzle\Http\Exception\ServerErrorResponseException;
*
* The web service may not return any information for an entire record, in
* which case all of the attributes for that record class will be empty.
+ *
+ * **Usage**
+ *
+ * The basic API for this class is the same for all of the web service end
+ * points. First you create a web service object with your MaxMind
+ * $userId
and $licenseKey
, then you call the method
+ * corresponding to a specific end point, passing it the IP address you want
+ * to look up.
+ *
+ * If the request succeeds, the method call will return a model class for
+ * the end point you called. This model in turn contains multiple record
+ * classes, each of which represents part of the data returned by the web
+ * service.
+ *
+ * If the request fails, the client class throws an exception.
+ *
+ * **Exceptions**
+ *
+ * For details on the possible errors returned by the web service itself, see
+ * {@link http://dev.maxmind.com/geoip2/geoip/web-services the GeoIP2 web
+ * service docs}.
+ *
+ * If the web service returns an explicit error document, this is thrown as a
+ * {@link \GeoIP2\Exception\WebserviceException}. If some other sort of
+ * transport error occurs, this is thrown as a {@link
+ * \GeoIP2\Exception\HttpException}. The difference is that the webservice
+ * error includes an error message and error code delivered by the web
+ * service. The latter is thrown when some sort of unanticipated error occurs,
+ * such as the web service returning a 500 or an invalid error document.
+ *
+ * If the web service returns any status code besides 200, 4xx, or 5xx, this
+ * also becomes a {@link \GeoIP2\Exception\HttpException}.
+ *
+ * Finally, if the web service returns a 200 but the body is invalid, the
+ * client throws a {@link \GeoIP2\Exception\GenericException}.
*/
class Client
{