From b191ab325047a815e4a94c2ae15fb55092901a1f Mon Sep 17 00:00:00 2001 From: Thomas Coffee Date: Thu, 13 Jul 2017 15:12:13 -0400 Subject: [PATCH] Polish Translate docs (#2210) --- .../com/google/cloud/translate/Detection.java | 4 +-- .../com/google/cloud/translate/Language.java | 2 +- .../com/google/cloud/translate/Translate.java | 36 +++++++++---------- .../cloud/translate/TranslateOptions.java | 17 +++++---- .../google/cloud/translate/Translation.java | 11 +++--- .../google/cloud/translate/package-info.java | 13 ++++--- 6 files changed, 41 insertions(+), 42 deletions(-) diff --git a/google-cloud-translate/src/main/java/com/google/cloud/translate/Detection.java b/google-cloud-translate/src/main/java/com/google/cloud/translate/Detection.java index 78dc5a519555..cd03501641b3 100644 --- a/google-cloud-translate/src/main/java/com/google/cloud/translate/Detection.java +++ b/google-cloud-translate/src/main/java/com/google/cloud/translate/Detection.java @@ -26,8 +26,8 @@ * Information about a language detection. Objects of this class contain the detected language and * possibly a confidence level. * - * Detecting Language - * + * @see Detecting + * Language */ public class Detection implements Serializable { diff --git a/google-cloud-translate/src/main/java/com/google/cloud/translate/Language.java b/google-cloud-translate/src/main/java/com/google/cloud/translate/Language.java index 031bffe9e64c..44e31d504393 100644 --- a/google-cloud-translate/src/main/java/com/google/cloud/translate/Language.java +++ b/google-cloud-translate/src/main/java/com/google/cloud/translate/Language.java @@ -25,7 +25,7 @@ /** * Information about a language supported by Google Translation. Objects of this class contain - * language's code and the language name. + * the language's code and the language name. * * @see * Discovering Supported Languages diff --git a/google-cloud-translate/src/main/java/com/google/cloud/translate/Translate.java b/google-cloud-translate/src/main/java/com/google/cloud/translate/Translate.java index 0c08e481da6a..1a14a542f85a 100644 --- a/google-cloud-translate/src/main/java/com/google/cloud/translate/Translate.java +++ b/google-cloud-translate/src/main/java/com/google/cloud/translate/Translate.java @@ -86,8 +86,8 @@ public static TranslateOption targetLanguage(String targetLanguage) { /** * Sets the language translation model. You can use this parameter to take advantage of Neural * Machine Translation. Possible values are {@code base} and {@code nmt}. Google Translation could - * use a different model to translate your text, use {@link Translation#getModel()} to know - * which model was used for translation. Please notice that you must be whitelisted to use this + * use a different model to translate your text: use {@link Translation#getModel()} to know + * which model was used for translation. Please note that you must be whitelisted to use this * option, otherwise translation will fail. * * @param model the language translation model @@ -98,19 +98,19 @@ public static TranslateOption model(String model) { } /** - * Returns the list of languages supported by Google Translation. If - * {@link LanguageListOption#targetLanguage(String)} is provided, {@link Language#getName()} - * values are localized according to the provided target language. If no such option is passed, - * {@link Language#getName()} values are localized according to + * Returns the list of languages supported by Google Translation. If an option from + * {@link LanguageListOption#targetLanguage(String)} is provided, the value of + * {@link Language#getName()} is localized according to the provided target language. If no such + * option is passed, the value of {@link Language#getName()} is localized according to * {@link TranslateOptions#getTargetLanguage()}. * *

Example of listing supported languages, localized according to - * {@link TranslateOptions#getTargetLanguage()}. + * {@link TranslateOptions#getTargetLanguage()}: * 

 {@code
    * List languages = translate.listSupportedLanguages();
    * }
* - *

Example of listing supported languages, localized according to a provided language. + *

Example of listing supported languages, localized according to a provided language: * 

 {@code
    * List languages = translate.listSupportedLanguages(
    *     LanguageListOption.targetLanguage("es"));
@@ -122,7 +122,7 @@ public static TranslateOption model(String model) {
   /**
    * Detects the language of the provided texts.
    *
-   * 
Example of detecting the language of some texts.
+   * 
Example of detecting the language of some texts:
    * 
 {@code
    * List texts = new LinkedList<>();
    * texts.add("Hello, World!");
@@ -132,21 +132,21 @@ public static TranslateOption model(String model) {
    *
    * @param texts the texts for which language should be detected
    * @return a list of objects containing information on the language detection, one for each
-   *     provided text, in order.
+   *     provided text, in order
    */
   List detect(List texts);
 
   /**
    * Detects the language of the provided texts.
    *
-   * 
Example of detecting the language of some texts.
+   * 
Example of detecting the language of some texts:
    * 
 {@code
    * List detections = translate.detect("Hello, World!", "¡Hola Mundo!");
    * }

    *
    * @param texts the texts for which language should be detected
    * @return a list of objects containing information on the language detection, one for each
-   *     provided text, in order.
+   *     provided text, in order
    */
   List detect(String... texts);
 
@@ -154,7 +154,7 @@ public static TranslateOption model(String model) {
    * Detects the language of the provided text. Returns an object containing information on the
    * language detection.
    *
-   * 
Example of detecting the language of a text.
+   * 
Example of detecting the language of a text:
    * 
 {@code
    * Detection detection = translate.detect("Hello, World!");
    * }

@@ -165,7 +165,7 @@ public static TranslateOption model(String model) {
   /**
    * Translates the provided texts.
    *
-   * 
Example of translating some texts.
+   * 
Example of translating some texts:
    * 
 {@code
    * List texts = new LinkedList<>();
    * texts.add("Hello, World!");
@@ -173,7 +173,7 @@ public static TranslateOption model(String model) {
    * List translations = translate.translate(texts);
    * }

    *
-   * 
Example of translating some texts, specifying source and target language.
+   * 
Example of translating some texts, specifying source and target language:
    * 
 {@code
    * List texts = new LinkedList<>();
    * texts.add("¡Hola Mundo!");
@@ -183,7 +183,7 @@ public static TranslateOption model(String model) {
    *
    * @param texts the texts to translate
    * @return a list of objects containing information on the language translation, one for each
-   *     provided text, in order.
+   *     provided text, in order
    * @throws TranslateException upon failure or if {@link TranslateOption#model(String)} is used by
    *     a non-whitelisted user
    */
@@ -192,12 +192,12 @@ public static TranslateOption model(String model) {
   /**
    * Translates the provided texts.
    *
-   * 
Example of translating a text.
+   * 
Example of translating a text:
    * 
 {@code
    * Translation translation = translate.translate("¡Hola Mundo!");
    * }

    *
-   * 
Example of translating a text, specifying source and target language.
+   * 
Example of translating a text, specifying source and target language:
    * 
 {@code
    * Translation translation = translate.translate("¡Hola Mundo!",
    *     TranslateOption.sourceLanguage("es"), TranslateOption.targetLanguage("de"));
diff --git a/google-cloud-translate/src/main/java/com/google/cloud/translate/TranslateOptions.java b/google-cloud-translate/src/main/java/com/google/cloud/translate/TranslateOptions.java
index 8934accbfd93..574c623d003c 100644
--- a/google-cloud-translate/src/main/java/com/google/cloud/translate/TranslateOptions.java
+++ b/google-cloud-translate/src/main/java/com/google/cloud/translate/TranslateOptions.java
@@ -100,7 +100,7 @@ public Builder setTransportOptions(TransportOptions transportOptions) {
     }
 
     /**
-     * Sets project id. Setting a project id has no impact on the {@link Translate} service.
+     * Sets the project ID. Setting a project ID has no impact on the {@link Translate} service.
      *
      * @return the builder
      */
@@ -114,8 +114,8 @@ public Builder setProjectId(String projectId) {
      * Sets the API key used to issue requests. This will be ignored if credentials are explicitly
      * set with {@link ServiceOptions.Builder#setCredentials setCredentials}. If neither are set,
      * and no Application Default Credentials are available, an API key is looked for in the
-     * {@code GOOGLE_API_KEY} environment variable. For instructions on how to get an API key see Translate quickstart.
+     * {@code GOOGLE_API_KEY} environment variable. For instructions on how to get an API key, see
+     * the Translate Quickstart.
      */
     @Deprecated
     public Builder setApiKey(String apiKey) {
@@ -125,11 +125,10 @@ public Builder setApiKey(String apiKey) {
 
 
     /**
-     * Sets the code for the default target language. If not set, English ({@code en}) is used.
-     * {@link Translate#translate(List, TranslateOption...)} and
-     * {@link Translate#translate(String, TranslateOption...)} calls will use this
-     * value unless a {@link TranslateOption#targetLanguage(String)} option is explicitly
-     * provided.
+     * Sets the code for the default target language. If not set, English ({@code en}) is
+     * used. Calls to {@link Translate#translate(List, TranslateOption...)} and
+     * {@link Translate#translate(String, TranslateOption...)} will use this value unless an option
+     * from {@link TranslateOption#targetLanguage(String)} is explicitly provided.
      *
      * @return the builder
      */
@@ -235,7 +234,7 @@ protected String getDefaultHost() {
 
 
   /**
-   * Returns the API key, to be used to send requests.
+   * Returns the API key to be used to send requests.
    */
   public String getApiKey() {
     return apiKey;
diff --git a/google-cloud-translate/src/main/java/com/google/cloud/translate/Translation.java b/google-cloud-translate/src/main/java/com/google/cloud/translate/Translation.java
index 3527203f64e9..88a33bdd431c 100644
--- a/google-cloud-translate/src/main/java/com/google/cloud/translate/Translation.java
+++ b/google-cloud-translate/src/main/java/com/google/cloud/translate/Translation.java
@@ -26,10 +26,11 @@
 
 /**
  * Information about a translation. Objects of this class contain the translated text and the source
- * language's code. Source language's code can be the one provided by the user (if any) or the one
- * detected by the Google Translation service.
+ * language's code. The source language's code can be optionally specified by the user or
+ * automatically detected by the Google Translation service.
  *
- * Translating Text
+ * @see Translating
+ * Text
  */
 public class Translation implements Serializable {
 
@@ -71,10 +72,10 @@ public String getSourceLanguage() {
 
   /**
    * Returns the translation model used to translate the text. This value is only available if
-   * {@link Translate.TranslateOption#model(String)} was passed to
+   * a result from {@link Translate.TranslateOption#model(String)} was passed to
    * {@link Translate#translate(List, Translate.TranslateOption...)}.
    *
-   * 
Please notice that you must be whitelisted to use the
+   * 
Please note that you must be whitelisted to use the
    * {@link Translate.TranslateOption#model(String)} option, otherwise translation will fail.
    */
   public String getModel() {
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
index ef5bc85a8ead..bb450a5be479 100644
--- 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,15 +17,14 @@
 /**
  * A client to Google Translation.
  *
- * 
Here's a simple usage example for using google-cloud. This example shows how to detect the
- * language of some text and how to translate some text. The example assumes that the
+ * 
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
- * 
- * DetectLanguageAndTranslate.java.
- * 
 {@code
- * Translate translate = TranslateOptions.getDefaultInstance().getService();
+ * the API key. For the complete source code, see: 
+ * DetectLanguageAndTranslate.java.  
+ * {@code Translate translate = TranslateOptions.getDefaultInstance().getService();
  *
  * Detection detection = translate.detect("Hola");
  * String detectedLanguage = detection.getLanguage();