Various fixes to doc wording, links, etc

docs/contents/cloud-datastore.json

@@ -13,17 +13,21 @@
     }, {
         "title": "Key",
         "type": "datastore/key"
-    }, {
-        "title": "Query",
-        "type": "datastore/query/query"
-    }, {
-        "title": "GQL Query",
-        "type": "datastore/query/gqlquery"
     }, {
         "title": "GeoPoint",
         "type": "datastore/geopoint"
     }, {
         "title": "Blob",
         "type": "datastore/blob"
+    }, {
+        "title": "Queries",
+        "type": "datastore/queryinterface",
+        "nav": [{
+            "title": "GQL Query",
+            "type": "datastore/query/gqlquery"
+        }, {
+            "title": "Query",
+            "type": "datastore/query/query"
+        }]
     }]
 }

src/Core/Iam/Iam.php

@@ -126,9 +126,6 @@ public function setPolicy(array $policy, array $options = [])
      *
      * Invalid permissions will raise a BadRequestException.
      *
-     * A list of allowed permissions can be found in the
-     * [access control documentation](https://cloud.google.com/pubsub/access_control#permissions).
-     *
      * Example:
      * ```
      * $allowedPermissions = $iam->testPermissions([

src/Datastore/DatastoreClient.php

@@ -42,9 +42,7 @@
  *
  * To enable the
  * [Google Cloud Datastore Emulator](https://cloud.google.com/datastore/docs/tools/datastore-emulator),
- * set the
- * [`PUBSUB_EMULATOR_HOST`](https://cloud.google.com/datastore/docs/tools/datastore-emulator#setting_environment_variables)
- * environment variable.
+ * set the [`DATASTORE_EMULATOR_HOST`](https://goo.gl/vCVZrY) environment variable.
  *
  * Example:
  * ```
@@ -365,7 +363,7 @@ public function geoPoint($latitude, $longitude)
      * $blob = $datastore->blob(file_get_contents(__DIR__ .'/family-photo.jpg'));
      * ```
      *
-     * @param string|resource|StreamInterface $value
+     * @param string|resource|StreamInterface $value The value to store in a blob.
      * @return Blob
      */
     public function blob($value)
@@ -487,6 +485,8 @@ public function transaction(array $options = [])
      * $datastore->insert($entity);
      * ```
      *
+     * @see https://cloud.google.com/datastore/docs/reference/rest/v1/projects/commit Commit API documentation
+     *
      * @param Entity $entity The entity to be inserted.
      * @param array $options [optional] Configuration options.
      * @return string The entity version.
@@ -517,6 +517,8 @@ public function insert(Entity $entity, array $options = [])
      * $datastore->insertBatch($entities);
      * ```
      *
+     * @see https://cloud.google.com/datastore/docs/reference/rest/v1/projects/commit Commit API documentation
+     *
      * @param Entity[] $entities The entities to be inserted.
      * @param array $options [optional] Configuration options.
      * @return array [Response Body](https://cloud.google.com/datastore/reference/rest/v1/projects/commit#response-body)
@@ -549,6 +551,8 @@ public function insertBatch(array $entities, array $options = [])
      * $datastore->update($entity);
      * ```
      *
+     * @see https://cloud.google.com/datastore/docs/reference/rest/v1/projects/commit Commit API documentation
+     *
      * @param Entity $entity The entity to be updated.
      * @param array $options [optional] {
      *     Configuration Options
@@ -589,6 +593,8 @@ public function update(Entity $entity, array $options = [])
      * $datastore->updateBatch($entities);
      * ```
      *
+     * @see https://cloud.google.com/datastore/docs/reference/rest/v1/projects/commit Commit API documentation
+     *
      * @param Entity[] $entities The entities to be updated.
      * @param array $options [optional] {
      *     Configuration Options
@@ -641,6 +647,8 @@ public function updateBatch(array $entities, array $options = [])
      * $datastore->upsert($entity);
      * ```
      *
+     * @see https://cloud.google.com/datastore/docs/reference/rest/v1/projects/commit Commit API documentation
+     *
      * @param Entity $entity The entity to be upserted.
      * @param array $options [optional] Configuration Options.
      * @return string The entity version.
@@ -681,6 +689,8 @@ public function upsert(Entity $entity, array $options = [])
      * $datastore->upsertBatch($entities);
      * ```
      *
+     * @see https://cloud.google.com/datastore/docs/reference/rest/v1/projects/commit Commit API documentation
+     *
      * @param Entity[] $entities The entities to be upserted.
      * @param array $options [optional] Configuration Options.
      * @return array [Response Body](https://cloud.google.com/datastore/reference/rest/v1/projects/commit#response-body)
@@ -708,6 +718,8 @@ public function upsertBatch(array $entities, array $options = [])
      * $datastore->delete($key);
      * ```
      *
+     * @see https://cloud.google.com/datastore/docs/reference/rest/v1/projects/commit Commit API documentation
+     *
      * @param Key $key The identifier to delete.
      * @param array $options [optional] {
      *     Configuration options
@@ -742,6 +754,8 @@ public function delete(Key $key, array $options = [])
      * $datastore->deleteBatch($keys);
      * ```
      *
+     * @see https://cloud.google.com/datastore/docs/reference/rest/v1/projects/commit Commit API documentation
+     *
      * @param Key[] $keys The identifiers to delete.
      * @param array $options [optional] {
      *     Configuration options
@@ -783,6 +797,8 @@ public function deleteBatch(array $keys, array $options = [])
      * }
      * ```
      *
+     * @see https://cloud.google.com/datastore/docs/reference/rest/v1/projects/lookup Lookup API documentation
+     *
      * @param Key $key The identifier to use to locate a desired entity.
      * @param array $options [optional] {
      *     Configuration Options
@@ -824,6 +840,8 @@ public function lookup(Key $key, array $options = [])
      * }
      * ```
      *
+     * @see https://cloud.google.com/datastore/docs/reference/rest/v1/projects/lookup Lookup API documentation
+     *
      * @param Key[] $key The identifiers to look up.
      * @param array $options [optional] {
      *     Configuration Options
@@ -942,6 +960,8 @@ public function gqlQuery($query, array $options = [])
      * }
      * ```
      *
+     * @see https://cloud.google.com/datastore/docs/reference/rest/v1/projects/runQuery RunQuery API documentation
+     *
      * @param QueryInterface $query A query object.
      * @param array $options [optional] {
      *     Configuration Options

src/Datastore/Entity.php

@@ -63,6 +63,8 @@
  * echo $entity['firstName']; // 'Bob'
  * $entity['location'] = 'Detroit, MI';
  * ```
+ *
+ * @see https://cloud.google.com/datastore/docs/reference/rest/v1/Entity Entity API documentation
  */
 class Entity implements ArrayAccess
 {
@@ -178,6 +180,8 @@ public function key()
      * $cursor = $entity->cursor();
      * ```
      *
+     * @see https://cloud.google.com/datastore/docs/reference/rest/v1/EntityResult EntityResult.cursor
+     *
      * @return string|null
      */
     public function cursor()
@@ -196,6 +200,8 @@ public function cursor()
      * $baseVersion = $entity->baseVersion();
      * ```
      *
+     * @see https://cloud.google.com/datastore/docs/reference/rest/v1/EntityResult EntitResult.version
+     *
      * @return string|null
      */
     public function baseVersion()

src/Datastore/Key.php

@@ -22,8 +22,6 @@
 use JsonSerializable;
 
 /**
- * Represents a Datastore Key.
- *
  * Keys are unique identifiers for entities.
  *
  * Keys may be considered either "named" or "incomplete". A named Key is one in

src/Datastore/Query/GqlQuery.php

@@ -27,7 +27,7 @@
  *
  * By default, parameters MUST be bound using named or positional bindings.
  * Literals are disabled by default, and must be enabled by setting
- * `$options['allowLiterals']` to `true`. As with any SQL-style language, using
+ * `$options['allowLiterals']` to `true`. As with any SQL dialect, using
  * parameter binding is highly recommended.
  *
  * Idiomatic usage is via {@see Google\Cloud\Datastore\DatastoreClient::gqlQuery()}.

src/Datastore/Query/Query.php

@@ -131,9 +131,10 @@ class Query implements QueryInterface
     private $query;
 
     /**
+     * @codingStandardsIgnoreStart
      * @param EntityMapper $entityMapper An instance of EntityMapper
-     * @param array $query [optional]
-     *        [Query](https://cloud.google.com/datastore/reference/rest/v1/projects/runQuery#query)
+     * @param array $query [optional] [Query](https://cloud.google.com/datastore/reference/rest/v1/projects/runQuery#query)
+     * @codingStandardsIgnoreEnd
      */
     public function __construct(EntityMapper $entityMapper, array $query = [])
     {
@@ -305,7 +306,10 @@ public function hasAncestor(Key $key)
      * @see https://cloud.google.com/datastore/reference/rest/v1/projects/runQuery#Direction Allowed Directions
      *
      * @param string $property The property to order by.
-     * @param string $direction The direction to order in.
+     * @param string $direction [optional] The direction to order in. Google
+     *        Cloud PHP provides class constants which map to allowed Datastore
+     *        values. Those constants are `Query::ORDER_DESCENDING` and
+     *        `Query::ORDER_ASCENDING`. **Defaults to** `Query::ORDER_ACENDING`.
      * @return Query
      */
     public function order($property, $direction = self::ORDER_DEFAULT)

src/Datastore/Query/QueryInterface.php

@@ -20,7 +20,9 @@
 use JsonSerializable;
 
 /**
- * Represents a Datastore Query
+ * Represents a Datastore Query.
+ *
+ * @see https://cloud.google.com/datastore/docs/concepts/queries Datastore Queries
  */
 interface QueryInterface extends JsonSerializable
 {

src/Datastore/Transaction.php

@@ -457,6 +457,8 @@ public function runQuery(QueryInterface $query, array $options = [])
      * $transaction->commit();
      * ```
      *
+     * @see https://cloud.google.com/datastore/docs/reference/rest/v1/projects/commit Commit API documentation
+     *
      * @param array $options [optional] Configuration Options.
      * @return array [Response Body](https://cloud.google.com/datastore/reference/rest/v1/projects/commit#response-body)
      */

src/Logging/PsrLogger.php

@@ -34,6 +34,8 @@
  *
  * $psrLogger = $logging->psrLogger('my-log');
  * ```
+ *
+ * @see http://www.php-fig.org/psr/psr-3/#psrlogloggerinterface Psr\Log\LoggerInterface
  */
 class PsrLogger implements LoggerInterface
 {

src/Vision/Annotation.php

@@ -214,6 +214,8 @@ public function info()
      * $faces = $annotation->faces();
      * ```
      *
+     * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#FaceAnnotation FaceAnnotation
+     *
      * @return Face[]|null
      */
     public function faces()
@@ -229,6 +231,8 @@ public function faces()
      * $landmarks = $annotation->landmarks();
      * ```
      *
+     * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#EntityAnnotation EntityAnnotation
+     *
      * @return Entity[]|null
      */
     public function landmarks()
@@ -244,6 +248,8 @@ public function landmarks()
      * $logos = $annotation->logos();
      * ```
      *
+     * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#EntityAnnotation EntityAnnotation
+     *
      * @return Entity[]|null
      */
     public function logos()
@@ -259,6 +265,8 @@ public function logos()
      * $labels = $annotation->labels();
      * ```
      *
+     * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#EntityAnnotation EntityAnnotation
+     *
      * @return Entity[]|null
      */
     public function labels()
@@ -274,6 +282,8 @@ public function labels()
      * $text = $annotation->text();
      * ```
      *
+     * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#EntityAnnotation EntityAnnotation
+     *
      * @return Entity[]|null
      */
     public function text()
@@ -306,6 +316,10 @@ public function fullText()
      * $safeSearch = $annotation->safeSearch();
      * ```
      *
+     * @codingStandardsIgnoreStart
+     * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#SafeSearchAnnotation SafeSearchAnnotation
+     * @codingStandardsIgnoreEnd
+     *
      * @return SafeSearch|null
      */
     public function safeSearch()
@@ -321,6 +335,8 @@ public function safeSearch()
      * $properties = $annotation->imageProperties();
      * ```
      *
+     * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#ImageProperties ImageProperties
+     *
      * @return ImageProperties|null
      */
     public function imageProperties()
@@ -336,6 +352,10 @@ public function imageProperties()
      * $hints = $annotation->cropHints();
      * ```
      *
+     * @codingStandardsIgnoreStart
+     * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#CropHintsAnnotation CropHintsAnnotation
+     * @codingStandardsIgnoreEnd
+     *
      * @return CropHint[]|null
      */
     public function cropHints()
@@ -351,6 +371,8 @@ public function cropHints()
      * $web = $annotation->web();
      * ```
      *
+     * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#WebDetection WebDetection
+     *
      * @return Web|null
      */
     public function web()

src/Vision/Annotation/CropHint.php

@@ -67,6 +67,8 @@
  *
  *     @return float
  * }
+ *
+ * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#CropHint CropHint
  */
 class CropHint extends AbstractFeature
 {

src/Vision/Annotation/Document.php

@@ -65,6 +65,8 @@
  *
  *     @return array
  * }
+ *
+ * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#TextAnnotation TextAnnotation
  */
 class Document extends AbstractFeature
 {

src/Vision/Annotation/ImageProperties.php

@@ -43,6 +43,8 @@
  *
  *     @return array
  * }
+ *
+ * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#ImageProperties ImageProperties
  */
 class ImageProperties extends AbstractFeature
 {

src/Vision/Annotation/SafeSearch.php

@@ -86,6 +86,8 @@
  *
  *     @return array
  * }
+ *
+ * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#SafeSearchAnnotation SafeSearchAnnotation
  */
 class SafeSearch extends AbstractFeature
 {

src/Vision/Annotation/Web.php

@@ -36,6 +36,8 @@
  *
  * $web = $annotation->web();
  * ```
+ *
+ * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#WebDetection WebDetection
  */
 class Web extends AbstractFeature
 {

src/Vision/Annotation/Web/WebEntity.php

@@ -69,6 +69,8 @@
  *
  *     @return string
  * }
+ *
+ * @see https://cloud.google.com/vision/docs/reference/rest/v1/images/annotate#WebEntity WebEntity
  */
 class WebEntity extends AbstractFeature
 {