Updated user guide to improve the CloudSearchDomainClient experience.

docs/_ext/aws/templates/client_intro

@@ -69,4 +69,6 @@ clients so that you only have to specify your settings once.
     $client = $aws->get('{{ namespace }}');
     {% endif %}
 
+For more information about configuration files, see :doc:`configuration`.
+
 .. _{{ namespace }}{{ apiVersionSuffix }}_operations:

docs/service-cloudsearch.rst

@@ -1,3 +1,9 @@
 .. service:: CloudSearch
 
+Searching and Uploading Documents
+---------------------------------
+
+To search or upload documents to your CloudSearch domain, you must use the
+:doc:`CloudSearchDomainClient <service-cloudsearchdomain>`.
+
 .. apiref:: CloudSearch

docs/service-cloudsearchdomain.rst

@@ -22,20 +22,52 @@ Similar to the way other service clients are used, you can instantiate the ``Clo
     use Aws\CloudSearchDomain\CloudSearchDomainClient;
 
     $client = CloudSearchDomainClient::factory(array(
-        'base_url' => '<your cloudsearch domain endpoint>',
+        'profile'  => '<profile in your aws credentials file>',
+        'base_url' => '<your cloudsearch domain endpoint>'
     ));
 
-The ``CloudSearchDomainClient`` is unlike other clients, because it does not require you to provide AWS credentials.
-The only thing you need to provide is the ``base_url`` option, which represents the domain's endpoint. Domain
-endpoints are unique to each domain, and you can get it by describing your domain with the :doc:`Amazon CloudSearch
-configuration client <service-cloudsearch>`.
+The ``CloudSearchDomainClient`` is unlike other clients, because it does not require you to provide a region. Instead,
+you must provide the ``base_url`` option, which represents the domain's endpoint. Domain endpoints are unique to each
+domain, and you can get it using the `DescribeDomains operation
+<http://docs.aws.amazon.com/aws-sdk-php/latest/class-Aws.CloudSearch.CloudSearchClient.html#_describeDomains>`_ of the
+:doc:`Amazon CloudSearch configuration client<service-cloudsearch>`.
+
+Service builder
+~~~~~~~~~~~~~~~
+
+Again, similar to other service clients, you can use the service builder to instantiate the client. This allows you to
+specify credentials and other configuration settings in a configuration file. These settings can then be shared across
+all clients so that you only have to specify your settings once.
+
+.. code-block:: php
+
+    use Aws\Common\Aws;
+
+    // Create a service builder using a configuration file
+    $aws = Aws::factory('/path/to/my_config.json');
+
+    // Get the client from the builder
+    $client = $aws->get('CloudSearchDomain');
+
+**Note:** This assumes that your configuration file has been setup to include the ``base_url`` option for the
+CloudSearch Domain service. If it is not, you can provide it manually when calling ``get()``.
+
+.. code-block:: php
+
+    $client = $aws->get('cloudsearchdomain', array(
+        'base_url' => '<your cloudsearch domain endpoint>'
+    ));
+
+For more information about configuration files, see :doc:`configuration`.
 
 Helper method
 ~~~~~~~~~~~~~
 
-An easy way to instantiate the ``CloudSearchDomainClient`` is to use the ``CloudSearchClient::getDomainClient()``
-helper method. This method use the CloudSearch configuration API to retrieve the domain endpoint, and instantiates the
-domain client for you.
+An easier way to instantiate the ``CloudSearchDomainClient`` is to use the ``CloudSearchClient::getDomainClient()``
+helper method. This method uses the CloudSearch configuration API to retrieve the domain endpoint and instantiate the
+``CloudSearchDomainClient`` for you. To use this method, you must specify the domain ID in the first argument, and an
+array of options (the same as you would use in the ``CloudSearchDomainClient::factory()`` method) in the second
+argument.
 
 .. code-block:: php
 
@@ -46,11 +78,43 @@ domain client for you.
         'region'  => '<region name>',
     ));
 
-    $domainClient = $configClient->getDomainClient('<domain name>');
+    $domainClient = $configClient->getDomainClient('<domain name>', array(
+        'profile' => '<profile in your aws credentials file>',
+    ));
+
+If you are planning to use the same credentials with your ``CloudSearchClient`` and ``CloudSearchDomainClient``, you
+can make a small optimization by doing the following, which will skip the typical credential resolving process.
+
+.. code-block:: php
+
+    $domainClient = $configClient->getDomainClient('<domain name>', array(
+        'credentials' => $configClient->getCredentials(),
+    ));
+
+The ``CloudSearchDomainClient`` can also be used without credentials if you have configured your domain's policy to
+allow anonymous access. To make the ``CloudSearchDomainClient`` anonymous, set ``'credentials'`` to ``false``.
+
+.. code-block:: php
+
+    $domainClient = $configClient->getDomainClient('<domain name>', array(
+        'credentials' => false,
+    ));
+
+**Note:** Credentials work the same way with the ``CloudSearchDomainClient`` as they do with other clients. To learn
+more, see :doc:`credentials`.
+
+Using the client
+----------------
+
+Here is an example of a simple search.
+
+.. code-block:: php
 
     // Use the search operation
     $result = $domainClient->search(array('query' => 'foobar'));
     $hitCount = $result->getPath('hits/found');
     echo "Number of Hits: {$hitCount}\n";
 
+You can find more information on the parameters supported in the Search operation by reading the API reference.
+
 .. apiref:: CloudSearchDomain

src/Aws/CloudSearch/CloudSearchClient.php

@@ -91,9 +91,11 @@ public static function factory($config = array())
      * @param array  $config     Config options for the CloudSearchDomainClient
      *
      * @return CloudSearchDomainClient
+     * @link http://docs.aws.amazon.com/aws-sdk-php/guide/latest/configuration.html#client-configuration-options
      */
     public function getDomainClient($domainName, array $config = array())
     {
+        // Determine the Domain client's base_url
         $config['base_url'] = $this->describeDomains(array(
             'DomainNames' => array($domainName)
         ))->getPath('DomainStatusList/0/SearchService/Endpoint');

src/Aws/CloudSearchDomain/CloudSearchDomainClient.php

@@ -46,16 +46,7 @@ public static function factory($config = array())
 
     /**
      * @internal
-     * @throws \Aws\Common\Exception\BadMethodCallException Do not call this method
-     */
-    public function setCredentials(CredentialsInterface $credentials)
-    {
-        throw new BadMethodCallException('The CloudSearchDomain client does not require AWS credentials.');
-    }
-
-    /**
-     * @internal
-     * @throws \Aws\Common\Exception\BadMethodCallException Do not call this method
+     * @throws BadMethodCallException Do not call this method.
      */
     public function setRegion($region)
     {