Polish Translate docs (#2210)

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.
  *
- * <a href="https://cloud.google.com/translate/v2/detecting-language-with-rest">Detecting Language
- *     </a>
+ * @see <a href="https://cloud.google.com/translate/v2/detecting-language-with-rest">Detecting
+ *     Language </a>
  */
 public class Detection implements Serializable {
 

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 <a href="https://cloud.google.com/translate/v2/discovering-supported-languages-with-rest">
  *     Discovering Supported Languages</a>

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()}.
    *
    * <p>Example of listing supported languages, localized according to
-   * {@link TranslateOptions#getTargetLanguage()}.
+   * {@link TranslateOptions#getTargetLanguage()}:
    * <pre> {@code
    * List<Language> languages = translate.listSupportedLanguages();
    * }</pre>
    *
-   * <p>Example of listing supported languages, localized according to a provided language.
+   * <p>Example of listing supported languages, localized according to a provided language:
    * <pre> {@code
    * List<Language> languages = translate.listSupportedLanguages(
    *     LanguageListOption.targetLanguage("es"));
@@ -122,7 +122,7 @@ public static TranslateOption model(String model) {
   /**
    * Detects the language of the provided texts.
    *
-   * <p>Example of detecting the language of some texts.
+   * <p>Example of detecting the language of some texts:
    * <pre> {@code
    * List<String> texts = new LinkedList<>();
    * texts.add("Hello, World!");
@@ -132,29 +132,29 @@ 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<Detection> detect(List<String> texts);
 
   /**
    * Detects the language of the provided texts.
    *
-   * <p>Example of detecting the language of some texts.
+   * <p>Example of detecting the language of some texts:
    * <pre> {@code
    * List<Detection> detections = translate.detect("Hello, World!", "¡Hola Mundo!");
    * }</pre>
    *
    * @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<Detection> detect(String... texts);
 
   /**
    * Detects the language of the provided text. Returns an object containing information on the
    * language detection.
    *
-   * <p>Example of detecting the language of a text.
+   * <p>Example of detecting the language of a text:
    * <pre> {@code
    * Detection detection = translate.detect("Hello, World!");
    * }</pre>
@@ -165,15 +165,15 @@ public static TranslateOption model(String model) {
   /**
    * Translates the provided texts.
    *
-   * <p>Example of translating some texts.
+   * <p>Example of translating some texts:
    * <pre> {@code
    * List<String> texts = new LinkedList<>();
    * texts.add("Hello, World!");
    * texts.add("¡Hola Mundo!");
    * List<Translation> translations = translate.translate(texts);
    * }</pre>
    *
-   * <p>Example of translating some texts, specifying source and target language.
+   * <p>Example of translating some texts, specifying source and target language:
    * <pre> {@code
    * List<String> 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.
    *
-   * <p>Example of translating a text.
+   * <p>Example of translating a text:
    * <pre> {@code
    * Translation translation = translate.translate("¡Hola Mundo!");
    * }</pre>
    *
-   * <p>Example of translating a text, specifying source and target language.
+   * <p>Example of translating a text, specifying source and target language:
    * <pre> {@code
    * Translation translation = translate.translate("¡Hola Mundo!",
    *     TranslateOption.sourceLanguage("es"), TranslateOption.targetLanguage("de"));

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 <a
-     * href="https://cloud.google.com/translate/v2/quickstart">Translate quickstart</a>.
+     * {@code GOOGLE_API_KEY} environment variable. For instructions on how to get an API key, see
+     * the <a href="https://cloud.google.com/translate/v2/quickstart">Translate Quickstart</a>.
      */
     @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;

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.
  *
- * <a href="https://cloud.google.com/translate/v2/translating-text-with-rest">Translating Text</a>
+ * @see <a href="https://cloud.google.com/translate/v2/translating-text-with-rest">Translating
+ * Text</a>
  */
 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...)}.
    *
-   * <p>Please notice that you must be whitelisted to use the
+   * <p>Please note that you must be whitelisted to use the
    * {@link Translate.TranslateOption#model(String)} option, otherwise translation will fail.
    */
   public String getModel() {

google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java

@@ -17,15 +17,14 @@
 /**
  * A client to Google Translation.
  *
- * <p>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
+ * <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 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();
+ * the 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();
  *
  * Detection detection = translate.detect("Hola");
  * String detectedLanguage = detection.getLanguage();