Make Translate auth documentation clear and consistent (#2208)

tcoffee-google · web-flow · commit 8e074f3c07de · 2017-07-14T01:25:58.000-04:00
* Make Translate auth documentation clear and consistent Additional updates prompted by #1594 / #2147. * Fix doc link * Fix Spanner doc example * Work around Javadoc bug https://bugs.openjdk.java.net/browse/JDK-8130754
diff --git a/README.md b/README.md
@@ -178,7 +178,7 @@ Storage storage = StorageOptions.getDefaultInstance().getService();
   ```
 
 If no credentials are provided, `google-cloud` will attempt to detect them from the environment
-using `GoogleCredentials.getApplicationDefault()` which will search for Default Application
+using `GoogleCredentials.getApplicationDefault()` which will search for Application Default
 Credentials in the following locations (in order):
 
 1. The credentials file pointed to by the `GOOGLE_APPLICATION_CREDENTIALS` environment variable
@@ -498,8 +498,8 @@ Google Cloud Language (Beta)
 
 ### Preview
 
-Here is a code snippet showing a simple usage example of LanguageServiceClient. The example assumes that either default application
-credentials or a valid API key are available. (See [Authentication section](#authentication) for more information)
+Here is a code snippet showing a simple usage example of LanguageServiceClient. The example assumes that either Application Default
+Credentials or a valid API key are available. (See [Authentication section](#authentication) for more information)
 ```java
  try (LanguageServiceClient languageServiceClient = LanguageServiceClient.create()) {
    Document document = Document.newBuilder().build();
@@ -516,7 +516,7 @@ Google Cloud Vision (Beta)
 ### Preview
 
 Here is a code snippet showing a simple usage example of ImageAnnotatorClient.
-The example assumes that either default application credentials or a valid API key
+The example assumes that either Application Default Credentials or a valid API key
 are available. (See [Authentication section](#authentication) for more information)
 ```java
  try (ImageAnnotatorClient imageAnnotatorClient = ImageAnnotatorClient.create()) {
@@ -751,8 +751,8 @@ Google Translation (Beta)
 #### Preview
 
 Here's a snippet showing a simple usage example. The example shows how to detect the language of
-some text and how to translate some text. The example assumes that either default application
-credentials or a valid API key are available. An API key stored in the `GOOGLE_API_KEY` environment
+some text and how to translate some text. The example assumes that either Application Default
+Credentials or a valid API key are available. An API key stored in the `GOOGLE_API_KEY` environment
 variable will be automatically detected. Complete source code can be found at
 [DetectLanguageAndTranslate.java](./google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java).
 
@@ -784,8 +784,8 @@ Google Cloud Speech (Alpha)
 
 ### Preview
 
-Here is a code snippet showing a simple usage example of SpeechClient. The example assumes that either default application
-credentials or a valid API key are available. (See [Authentication section](#authentication) for more information)
+Here is a code snippet showing a simple usage example of SpeechClient. The example assumes that either Application Default
+Credentials or a valid API key are available. (See [Authentication section](#authentication) for more information)
 Note that you must provide a uri to a FLAC audio file to run this.
 
 ```java
@@ -814,8 +814,8 @@ Google Cloud Trace (Alpha)
 
 ### Preview
 
-Here is a code snippet showing a simple usage example of TraceServiceClient. The example assumes that either default application
-credentials or a valid API key are available.
+Here is a code snippet showing a simple usage example of TraceServiceClient. The example assumes that either Application Default
+Credentials or a valid API key are available.
 Note that you must [supply credentials](#authentication) and a project ID if running this snippet elsewhere.
 ```java
  try (TraceServiceClient traceServiceClient = TraceServiceClient.create()) {
@@ -832,8 +832,8 @@ Google Cloud Video Intelligence (Alpha)
 
 ### Preview
 
-Here is a code snippet showing a simple usage example of TraceServiceClient. The example assumes that either default application
-credentials or a valid API key are available.
+Here is a code snippet showing a simple usage example of TraceServiceClient. The example assumes that either Application Default
+Credentials or a valid API key are available.
 Note that you must [supply credentials](#authentication) and a project ID if running this snippet elsewhere.
 ```java
 try (VideoIntelligenceServiceClient videoIntelligenceServiceClient =
diff --git a/google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java b/google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java
@@ -37,8 +37,9 @@ public class DetectLanguageAndTranslate {
   public static void main(String... args) {
     // Create a service object
     //
-    // Requests are authenticated using default application credentials if available; otherwise,
-    // using an API key from the GOOGLE_API_KEY environment variable
+    // If no explicit credentials or API key are set, requests are authenticated using Application
+    // Default Credentials if available; otherwise, using an API key from the GOOGLE_API_KEY
+    // environment variable
     Translate translate = TranslateOptions.getDefaultInstance().getService();
 
     // Detect the language of some text
diff --git a/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java b/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java
@@ -218,13 +218,13 @@ public interface DatabaseClient {
    * returned runner can only be used once.
    *
    * <p>Example of a read write transaction.
-   * <pre> {@code
+   * <pre> <code>
    * long singerId = my_singer_id;
    * TransactionRunner runner = dbClient.readWriteTransaction();
    * runner.run(
-   *     new TransactionCallable<Void>() {
+   *     new TransactionCallable&lt;Void&gt;() {
    * 
-   *       @Override
+   *       {@literal @}Override
    *       public Void run(TransactionContext transaction) throws Exception {
    *         String column = "FirstName";
    *         Struct row =
@@ -235,7 +235,7 @@ public interface DatabaseClient {
    *         return null;
    *       }
    *     });
-   * }</pre>
+   * </code></pre>
    *
    */
   TransactionRunner readWriteTransaction();
diff --git a/google-cloud-translate/README.md b/google-cloud-translate/README.md
@@ -80,7 +80,7 @@ section to add `google-cloud-translate` as a dependency in your code.
 
 #### Creating an authorized service object
 To make authenticated requests to Google Translation, you must create a service object with
-credentials or with an API key. The simplest way to authenticate is to use
+credentials or use an API key. The simplest way to authenticate is to use
 [Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials).
 These credentials are automatically inferred from your environment, so you only need the following
 code to create your service object:
@@ -142,8 +142,8 @@ Translation translation = translate.translate(
 
 In
 [DetectLanguageAndTranslate.java](../google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java)
-we put together all the code shown above into one program. The program assumes that either default
-application credentials or a valid api key are available.
+we put together all the code shown above into one program. The program assumes that either Application
+Default Credentials or a valid API key are available.
 
 Troubleshooting
 ---------------
diff --git a/google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java b/google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java
@@ -17,11 +17,13 @@
 /**
  * A client to Google Translation.
  *
- * <p>Here's a simple usage example for using Google Cloud Translation. This example shows how to
- * detect the language of some text and how to translate some text. The example assumes that the
- * {@code GOOGLE_API_KEY} is set and contains a valid API key. Alternatively, you can use
- * {@link com.google.cloud.translate.TranslateOptions.Builder#setApiKey(java.lang.String)} to set
- * the API key. For the complete source code, see: <a
+ * <p>Here's a simple usage example for Google Cloud Translation. This example shows how to detect
+ * the language of some text and how to translate some text. The example assumes that either
+ * Application Default Credentials are available or that the {@code GOOGLE_API_KEY} environment
+ * variable is set and contains a valid API key. Alternatively, you can use
+ * {@link com.google.cloud.ServiceOptions.Builder#setCredentials setCredentials} to set credentials,
+ * or {@link com.google.cloud.translate.TranslateOptions.Builder#setApiKey(java.lang.String)} to set
+ * an API key. For the complete source code see <a
  * href="https://github.com/GoogleCloudPlatform/google-cloud-java/tree/master/google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java">
  * DetectLanguageAndTranslate.java</a>.  <pre>
  * {@code Translate translate = TranslateOptions.getDefaultInstance().getService();
