Add snippets to Translate's javadoc and TranslateSnippets class

gcloud-java-examples/pom.xml

@@ -32,6 +32,12 @@
       <artifactId>maven-assembly-plugin</artifactId>
       <version>2.5.4</version>
     </dependency>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <version>4.12</version>
+      <scope>test</scope>
+    </dependency>
   </dependencies>
   <build>
     <plugins>

gcloud-java-examples/src/main/java/com/google/cloud/examples/translate/snippets/TranslateSnippets.java

@@ -0,0 +1,157 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ * EDITING INSTRUCTIONS
+ * This file is referenced in Translate's javadoc. Any change to this file should be reflected in
+ * Translate's javadoc.
+ */
+
+package com.google.cloud.examples.translate.snippets;
+
+import com.google.cloud.translate.Detection;
+import com.google.cloud.translate.Language;
+import com.google.cloud.translate.Translate;
+import com.google.cloud.translate.Translate.LanguageListOption;
+import com.google.cloud.translate.Translate.TranslateOption;
+import com.google.cloud.translate.TranslateOptions;
+import com.google.cloud.translate.Translation;
+
+import java.util.LinkedList;
+import java.util.List;
+
+/**
+ * This class contains a number of snippets for the {@link Translate} interface.
+ */
+public class TranslateSnippets {
+
+  private final Translate translate;
+
+  public TranslateSnippets(Translate translate) {
+    this.translate = translate;
+  }
+
+  /**
+   * Example of listing supported languages, localized according to
+   * {@link TranslateOptions#targetLanguage()}.
+   */
+  // [TARGET listSupportedLanguages(LanguageListOption...)]
+  public List<Language> listSupportedLanguages() {
+    // [START listSupportedLanguages]
+    List<Language> languages = translate.listSupportedLanguages();
+    // [END listSupportedLanguages]
+    return languages;
+  }
+
+  /**
+   * Example of listing supported languages, localized according to a provided language.
+   */
+  // [TARGET listSupportedLanguages(LanguageListOption...)]
+  public List<Language> listSupportedLanguagesWithTarget() {
+    // [START listSupportedLanguagesWithTarget]
+    List<Language> languages = translate.listSupportedLanguages(
+        LanguageListOption.targetLanguage("es"));
+    // [END listSupportedLanguagesWithTarget]
+    return languages;
+  }
+
+  /**
+   * Example of detecting the language of some texts.
+   */
+  // [TARGET detect(List)]
+  public List<Detection> detectLanguageOfTextList() {
+    // [START detectLanguageOfTextList]
+    List<String> texts = new LinkedList<>();
+    texts.add("Hello, World!");
+    texts.add("¡Hola Mundo!");
+    List<Detection> detections = translate.detect(texts);
+    // [END detectLanguageOfTextList]
+    return detections;
+  }
+
+  /**
+   * Example of detecting the language of some texts.
+   */
+  // [TARGET detect(String...)]
+  public List<Detection> detectLanguageOfTexts() {
+    // [START detectLanguageOfTexts]
+    List<Detection> detections = translate.detect("Hello, World!", "¡Hola Mundo!");
+    // [END detectLanguageOfTexts]
+    return detections;
+  }
+
+  /**
+   * Example of detecting the language of a text.
+   */
+  // [TARGET detect(String)]
+  public Detection detectLanguageOfText() {
+    // [START detect]
+    Detection detection = translate.detect("Hello, World!");
+    // [END detect]
+    return detection;
+  }
+
+  /**
+   * Example of translating some texts.
+   */
+  // [TARGET translate(List, TranslateOption...)]
+  public List<Translation> translateTexts() {
+    // [START translateTexts]
+    List<String> texts = new LinkedList<>();
+    texts.add("Hello, World!");
+    texts.add("¡Hola Mundo!");
+    List<Translation> translations = translate.translate(texts);
+    // [END translateTexts]
+    return translations;
+  }
+
+  /**
+   * Example of translating some texts, specifying source and target language.
+   */
+  // [TARGET translate(List, TranslateOption...)]
+  public List<Translation> translateTextsWithOptions() {
+    // [START translateTextsWithOptions]
+    List<String> texts = new LinkedList<>();
+    texts.add("¡Hola Mundo!");
+    List<Translation> translations = translate.translate(texts,
+        TranslateOption.sourceLanguage("es"), TranslateOption.targetLanguage("de"));
+    // [END translateTextsWithOptions]
+    return translations;
+  }
+
+  /**
+   * Example of translating a text.
+   */
+  // [TARGET translate(String, TranslateOption...)]
+  public Translation translateText() {
+    // [START translateText]
+    Translation translation = translate.translate("¡Hola Mundo!");
+    // [END translateText]
+    return translation;
+  }
+
+  /**
+   * Example of translating a text, specifying source and target language.
+   */
+  // [TARGET translate(String, TranslateOption...)]
+  public Translation translateTextWithOptions() {
+    // [START translateTextWithOptions]
+    Translation translation = translate.translate("¡Hola Mundo!",
+        TranslateOption.sourceLanguage("es"), TranslateOption.targetLanguage("de"));
+    // [END translateTextWithOptions]
+    return translation;
+  }
+}

gcloud-java-examples/src/test/java/com/google/cloud/examples/translate/snippets/ITTranslateSnippets.java

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.examples.translate.snippets;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+
+import com.google.cloud.translate.Detection;
+import com.google.cloud.translate.Language;
+import com.google.cloud.translate.Translation;
+import com.google.cloud.translate.testing.RemoteTranslateHelper;
+
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+public class ITTranslateSnippets {
+
+  private static TranslateSnippets translateSnippets;
+
+  private static final String[] LANGUAGES = {"af", "sq", "ar", "hy", "az", "eu", "be", "bn", "bs",
+      "bg", "ca", "ceb", "ny", "zh-TW", "hr", "cs", "da", "nl", "en", "eo", "et", "tl", "fi", "fr",
+      "gl", "ka", "de", "el", "gu", "ht", "ha", "iw", "hi", "hmn", "hu", "is", "ig", "id", "ga",
+      "it", "ja", "jw", "kn", "kk", "km", "ko", "lo", "la", "lv", "lt", "mk", "mg", "ms", "ml",
+      "mt", "mi", "mr", "mn", "my", "ne", "no", "fa", "pl", "pt", "ro", "ru", "sr", "st", "si",
+      "sk", "sl", "so", "es", "su", "sw", "sv", "tg", "ta", "te", "th", "tr", "uk", "ur", "uz",
+      "vi", "cy", "yi", "yo", "zu"};
+
+  @BeforeClass
+  public static void beforeClass() {
+    RemoteTranslateHelper helper = RemoteTranslateHelper.create();
+    translateSnippets = new TranslateSnippets(helper.options().service());
+  }
+
+  @Test
+  public void testListSupportedLanguages() {
+    Set<String> supportedLanguages = new HashSet<>();
+    List<Language> languages = translateSnippets.listSupportedLanguages();
+    for (Language language : languages) {
+      supportedLanguages.add(language.code());
+      assertNotNull(language.name());
+    }
+    for (String code : LANGUAGES) {
+      assertTrue(supportedLanguages.contains(code));
+    }
+  }
+
+  @Test
+  public void testListSupportedLanguagesWithTarget() {
+    Set<String> supportedLanguages = new HashSet<>();
+    List<Language> languages = translateSnippets.listSupportedLanguagesWithTarget();
+    for (Language language : languages) {
+      supportedLanguages.add(language.code());
+      assertNotNull(language.name());
+    }
+    for (String code : LANGUAGES) {
+      assertTrue(supportedLanguages.contains(code));
+    }
+  }
+
+  @Test
+  public void testDetectLanguageOfTexts() {
+    List<Detection> detections = translateSnippets.detectLanguageOfTexts();
+    Detection detection = detections.get(0);
+    assertEquals("en", detection.language());
+    detection = detections.get(1);
+    assertEquals("es", detection.language());
+  }
+
+  @Test
+  public void testDetectLanguageOfTextList() {
+    List<Detection> detections = translateSnippets.detectLanguageOfTextList();
+    Detection detection = detections.get(0);
+    assertEquals("en", detection.language());
+    detection = detections.get(1);
+    assertEquals("es", detection.language());
+  }
+
+  @Test
+  public void testDetectLanguageOfText() {
+    Detection detection = translateSnippets.detectLanguageOfText();
+    assertEquals("en", detection.language());
+  }
+
+  @Test
+  public void testTranslateTextList() {
+    List<Translation> translations = translateSnippets.translateTexts();
+    Translation translation = translations.get(0);
+    assertEquals("Hello, World!", translation.translatedText());
+    assertEquals("en", translation.sourceLanguage());
+    translation = translations.get(1);
+    assertEquals("Hello World!", translation.translatedText());
+    assertEquals("es", translation.sourceLanguage());
+  }
+
+  @Test
+  public void testTranslateText() {
+    Translation translation = translateSnippets.translateText();
+    assertEquals("Hello World!", translation.translatedText());
+    assertEquals("es", translation.sourceLanguage());
+  }
+
+  @Test
+  public void testTranslateTextWithOptions() {
+    Translation translation = translateSnippets.translateTextWithOptions();
+    assertEquals("Hallo Welt!", translation.translatedText());
+    assertEquals("es", translation.sourceLanguage());
+  }
+}

gcloud-java-translate/src/main/java/com/google/cloud/translate/Translate.java

@@ -91,22 +91,24 @@ public static TranslateOption targetLanguage(String targetLanguage) {
    * {@link TranslateOptions#targetLanguage()}.
    *
    * <p>Example of listing supported languages, localized according to
-   * {@link TranslateOptions#targetLanguage()}:
+   * {@link TranslateOptions#targetLanguage()}.
    * <pre> {@code
    * List<Language> languages = translate.listSupportedLanguages();
    * }</pre>
-   * Or according to another target language:
+   *
+   * <p>Example of listing supported languages, localized according to a provided language.
    * <pre> {@code
    * List<Language> languages = translate.listSupportedLanguages(
    *     LanguageListOption.targetLanguage("es"));
    * }</pre>
+   *
    */
   List<Language> listSupportedLanguages(LanguageListOption... options);
 
   /**
    * 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!");
@@ -123,7 +125,7 @@ public static TranslateOption targetLanguage(String targetLanguage) {
   /**
    * 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>
@@ -138,25 +140,26 @@ public static TranslateOption targetLanguage(String targetLanguage) {
    * Detects the language of the provided text. Returns an object containing information on the
    * language detection.
    *
-   * <p>Example of detecting the language a text:
+   * <p>Example of detecting the language of a text.
    * <pre> {@code
    * Detection detection = translate.detect("Hello, World!");
    * }</pre>
+   *
    */
   Detection detect(String text);
 
   /**
    * 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!");
@@ -173,12 +176,12 @@ public static TranslateOption targetLanguage(String targetLanguage) {
   /**
    * 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"));