From 13b5a166bba35aed64c30cb3e1d92eb4ccdf5ca8 Mon Sep 17 00:00:00 2001
From: Gregory Oschwald <goschwald@maxmind.com>
Date: Fri, 10 May 2013 13:11:48 -0700
Subject: [PATCH] Added some usage text to the API docs too

---
 README.md                        |  2 +-
 src/GeoIP2/Webservice/Client.php | 35 ++++++++++++++++++++++++++++++++
 2 files changed, 36 insertions(+), 1 deletion(-)

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
+ * <code>$userId</code> and <code>$licenseKey</code>, 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
 {