From cfde3a2abd9eef6c1d647ac6e297345ff075fddb Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Thu, 2 Aug 2018 10:49:01 -0700 Subject: [PATCH] Move Translate snippets to test file, use new snippets.go for inclusion. Updates snippets.go utility to Deindent and Indent by one space. Updates to samples which are included in the docs to meet our cdpe-snippets-rubric (show imports, show client construction, show how to use the resulting object). I will follow-up with a PR to java-docs-samples to remove any redundant snippets from that repo. Why move to a test file? We are considering moving all snippets-style samples to test files to avoid redundant work involved with keeping snippets separate from test files. The important thing for snippets is that they are runnable and copy-pastable. Ran snippets utility to include snippets in JavaDoc. ./utilities/snippets \ ./google-cloud-examples/src/test/java/com/google/cloud/examples/translate/snippets/ITTranslateSnippets.java \ ./google-cloud-clients/google-cloud-translate/src/main/java/com/google/cloud/translate/Translate.java --- .../com/google/cloud/translate/Translate.java | 92 ++++++++-- .../translate/snippets/TranslateSnippets.java | 157 ------------------ .../snippets/ITTranslateSnippets.java | 114 +++++++++++-- utilities/snippets.go | 9 +- 4 files changed, 184 insertions(+), 188 deletions(-) delete mode 100644 google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/TranslateSnippets.java diff --git a/google-cloud-clients/google-cloud-translate/src/main/java/com/google/cloud/translate/Translate.java b/google-cloud-clients/google-cloud-translate/src/main/java/com/google/cloud/translate/Translate.java index 77678b804748..113077fdd2f6 100644 --- a/google-cloud-clients/google-cloud-translate/src/main/java/com/google/cloud/translate/Translate.java +++ b/google-cloud-clients/google-cloud-translate/src/main/java/com/google/cloud/translate/Translate.java @@ -116,15 +116,35 @@ public static TranslateOption format(String format) { * *

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

 {@code
+   * 
+   * 
{@code
+   * // TODO(developer): Uncomment these lines.
+   * // import com.google.cloud.translate.*;
+   * // Translate translate = TranslateOptions.getDefaultInstance().getService();
+   *
    * List languages = translate.listSupportedLanguages();
+   *
+   * for (Language language : languages) {
+   *   System.out.printf("Name: %s, Code: %s\n", language.getName(), language.getCode());
+   * }
    * }

+   * 
    *
    * 
Example of listing supported languages, localized according to a provided language:
-   * 
 {@code
+   * 
+   * 
{@code
+   * // TODO(developer): Uncomment these lines.
+   * // import com.google.cloud.translate.*;
+   * // Translate translate = TranslateOptions.getDefaultInstance().getService();
+   *
    * List languages = translate.listSupportedLanguages(
-   *     LanguageListOption.targetLanguage("es"));
+   *         Translate.LanguageListOption.targetLanguage("es"));
+   *
+   * for (Language language : languages) {
+   *   System.out.printf("Name: %s, Code: %s\n", language.getName(), language.getCode());
+   * }
    * }

+   * 
    *
    */
   List listSupportedLanguages(LanguageListOption... options);
@@ -133,13 +153,24 @@ public static TranslateOption format(String format) {
    * Detects the language of the provided texts.
    *
    * 
Example of detecting the language of some texts:
-   * 
 {@code
+   * 
+   * 
{@code
+   * // TODO(developer): Uncomment these lines.
+   * // import com.google.cloud.translate.*;
+   * // Translate translate = TranslateOptions.getDefaultInstance().getService();
+   *
    * List texts = new LinkedList<>();
    * texts.add("Hello, World!");
    * texts.add("¡Hola Mundo!");
    * List detections = translate.detect(texts);
-   * }

    *
+   * System.out.println("Language(s) detected:");
+   * for (Detection detection : detections) {
+   *   System.out.printf("\t%s\n", detection);
+   * }
+   * }

+   * 
+
    * @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
@@ -150,9 +181,11 @@ public static TranslateOption format(String format) {
    * Detects the language of the provided texts.
    *
    * 
Example of detecting the language of some texts:
-   * 
 {@code
+   * 
+   * 
{@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
@@ -165,9 +198,11 @@ public static TranslateOption format(String format) {
    * language detection.
    *
    * 
Example of detecting the language of a text:
-   * 
 {@code
+   * 
+   * 
{@code
    * Detection detection = translate.detect("Hello, World!");
    * }

+   * 
    *
    */
   Detection detect(String text);
@@ -176,20 +211,26 @@ public static TranslateOption format(String format) {
    * Translates the provided texts.
    *
    * 
Example of translating some texts:
-   * 
 {@code
+   * 
+   * 
{@code
    * List texts = new LinkedList<>();
    * texts.add("Hello, World!");
    * texts.add("¡Hola Mundo!");
    * List translations = translate.translate(texts);
    * }

+   * 
    *
    * 
Example of translating some texts, specifying source and target language:
-   * 
 {@code
+   * 
+   * 
{@code
    * List texts = new LinkedList<>();
    * texts.add("¡Hola Mundo!");
-   * List translations = translate.translate(texts,
-   *     TranslateOption.sourceLanguage("es"), TranslateOption.targetLanguage("de"));
+   * List translations = translate.translate(
+   *     texts,
+   *     Translate.TranslateOption.sourceLanguage("es"),
+   *     Translate.TranslateOption.targetLanguage("de"));
    * }

+   * 
    *
    * @param texts the texts to translate
    * @return a list of objects containing information on the language translation, one for each
@@ -200,18 +241,35 @@ public static TranslateOption format(String format) {
   List translate(List texts, TranslateOption... options);
 
   /**
-   * Translates the provided texts.
+   * Translates the provided text.
    *
    * 
Example of translating a text:
-   * 
 {@code
+   * 
+   * 
{@code
+   * // TODO(developer): Uncomment these lines.
+   * // import com.google.cloud.translate.*;
+   * // Translate translate = TranslateOptions.getDefaultInstance().getService();
+   *
    * Translation translation = translate.translate("¡Hola Mundo!");
+   * System.out.printf("Translated Text:\n\t%s\n", translation.getTranslatedText());
    * }

+   * 
+   *
+   * 
Example of translating a text, specifying source and target language and premium model:
+   * 
+   * 
{@code
+   * Translation translation = translate.translate(
+   *     "Hola Mundo!",
+   *     Translate.TranslateOption.sourceLanguage("es"),
+   *     Translate.TranslateOption.targetLanguage("de"),
+   *     // Use "base" for standard edition, "nmt" for the premium model.
+   *     Translate.TranslateOption.model("nmt"));
    *
-   * 
Example of translating a text, specifying source and target language:
-   * 
 {@code
-   * Translation translation = translate.translate("¡Hola Mundo!",
-   *     TranslateOption.sourceLanguage("es"), TranslateOption.targetLanguage("de"));
+   * System.out.printf(
+   *     "TranslatedText:\nText: %s\n",
+   *     translation.getTranslatedText());
    * }

+   * 
    *
    * @param text the text to translate
    * @return an object containing information on the language translation
diff --git a/google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/TranslateSnippets.java b/google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/TranslateSnippets.java
deleted file mode 100644
index 180c63c52113..000000000000
--- a/google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/TranslateSnippets.java
+++ /dev/null
@@ -1,157 +0,0 @@
-/*
- * Copyright 2016 Google LLC
- *
- * 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#getTargetLanguage()}.
-   */
-  // [TARGET listSupportedLanguages(LanguageListOption...)]
-  public List listSupportedLanguages() {
-    // [START listSupportedLanguages]
-    List languages = translate.listSupportedLanguages();
-    // [END listSupportedLanguages]
-    return languages;
-  }
-
-  /**
-   * Example of listing supported languages, localized according to a provided language.
-   */
-  // [TARGET listSupportedLanguages(LanguageListOption...)]
-  public List listSupportedLanguagesWithTarget() {
-    // [START listSupportedLanguagesWithTarget]
-    List languages = translate.listSupportedLanguages(
-        LanguageListOption.targetLanguage("es"));
-    // [END listSupportedLanguagesWithTarget]
-    return languages;
-  }
-
-  /**
-   * Example of detecting the language of some texts.
-   */
-  // [TARGET detect(List)]
-  public List detectLanguageOfTextList() {
-    // [START detectLanguageOfTextList]
-    List texts = new LinkedList<>();
-    texts.add("Hello, World!");
-    texts.add("¡Hola Mundo!");
-    List detections = translate.detect(texts);
-    // [END detectLanguageOfTextList]
-    return detections;
-  }
-
-  /**
-   * Example of detecting the language of some texts.
-   */
-  // [TARGET detect(String...)]
-  public List detectLanguageOfTexts() {
-    // [START detectLanguageOfTexts]
-    List 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 translateTexts() {
-    // [START translateTexts]
-    List texts = new LinkedList<>();
-    texts.add("Hello, World!");
-    texts.add("¡Hola Mundo!");
-    List translations = translate.translate(texts);
-    // [END translateTexts]
-    return translations;
-  }
-
-  /**
-   * Example of translating some texts, specifying source and target language.
-   */
-  // [TARGET translate(List, TranslateOption...)]
-  public List translateTextsWithOptions() {
-    // [START translateTextsWithOptions]
-    List texts = new LinkedList<>();
-    texts.add("¡Hola Mundo!");
-    List 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;
-  }
-}
diff --git a/google-cloud-examples/src/test/java/com/google/cloud/examples/translate/snippets/ITTranslateSnippets.java b/google-cloud-examples/src/test/java/com/google/cloud/examples/translate/snippets/ITTranslateSnippets.java
index 9a36437a5047..ddfa0371cf9e 100644
--- a/google-cloud-examples/src/test/java/com/google/cloud/examples/translate/snippets/ITTranslateSnippets.java
+++ b/google-cloud-examples/src/test/java/com/google/cloud/examples/translate/snippets/ITTranslateSnippets.java
@@ -22,6 +22,7 @@
 
 import com.google.cloud.translate.Detection;
 import com.google.cloud.translate.Language;
+import com.google.cloud.translate.Translate;
 import com.google.cloud.translate.Translation;
 import com.google.cloud.translate.testing.RemoteTranslateHelper;
 
@@ -29,12 +30,21 @@
 import org.junit.Test;
 
 import java.util.HashSet;
+import java.util.LinkedList;
 import java.util.List;
 import java.util.Set;
 
+/**
+ * This class contains a number of snippets for the {@link Translate} interface.
+ *
+ * 
After modifying snippets in this file, run {@code ./utilities/snippets
+ * ./google-cloud-examples/src/test/java/com/google/cloud/examples/translate/snippets/ITTranslateSnippets.java
+ * ./google-cloud-clients/google-cloud-translate/src/main/java/com/google/cloud/translate/Translate.java}
+ * to include the snippets in the Javadoc.
+ */
 public class ITTranslateSnippets {
 
-  private static TranslateSnippets translateSnippets;
+  private static Translate translate;
 
   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",
@@ -47,13 +57,24 @@ public class ITTranslateSnippets {
   @BeforeClass
   public static void beforeClass() {
     RemoteTranslateHelper helper = RemoteTranslateHelper.create();
-    translateSnippets = new TranslateSnippets(helper.getOptions().getService());
+    translate = helper.getOptions().getService();
   }
 
   @Test
   public void testListSupportedLanguages() {
+    // [START translate_list_codes]
+    // TODO(developer): Uncomment these lines.
+    // import com.google.cloud.translate.*;
+    // Translate translate = TranslateOptions.getDefaultInstance().getService();
+
+    List languages = translate.listSupportedLanguages();
+
+    for (Language language : languages) {
+      System.out.printf("Name: %s, Code: %s\n", language.getName(), language.getCode());
+    }
+    // [END translate_list_codes]
+
     Set supportedLanguages = new HashSet<>();
-    List languages = translateSnippets.listSupportedLanguages();
     for (Language language : languages) {
       supportedLanguages.add(language.getCode());
       assertNotNull(language.getName());
@@ -65,8 +86,20 @@ public void testListSupportedLanguages() {
 
   @Test
   public void testListSupportedLanguagesWithTarget() {
+    // [START translate_list_language_names]
+    // TODO(developer): Uncomment these lines.
+    // import com.google.cloud.translate.*;
+    // Translate translate = TranslateOptions.getDefaultInstance().getService();
+
+    List languages = translate.listSupportedLanguages(
+            Translate.LanguageListOption.targetLanguage("es"));
+
+    for (Language language : languages) {
+      System.out.printf("Name: %s, Code: %s\n", language.getName(), language.getCode());
+    }
+    // [END translate_list_language_names]
+
     Set supportedLanguages = new HashSet<>();
-    List languages = translateSnippets.listSupportedLanguagesWithTarget();
     for (Language language : languages) {
       supportedLanguages.add(language.getCode());
       assertNotNull(language.getName());
@@ -78,7 +111,10 @@ public void testListSupportedLanguagesWithTarget() {
 
   @Test
   public void testDetectLanguageOfTexts() {
-    List detections = translateSnippets.detectLanguageOfTexts();
+    // SNIPPET translate_detect_language_array
+    List detections = translate.detect("Hello, World!", "¡Hola Mundo!");
+    // SNIPPET translate_detect_language_array
+
     Detection detection = detections.get(0);
     assertEquals("en", detection.getLanguage());
     detection = detections.get(1);
@@ -87,7 +123,22 @@ public void testDetectLanguageOfTexts() {
 
   @Test
   public void testDetectLanguageOfTextList() {
-    List detections = translateSnippets.detectLanguageOfTextList();
+    // [START translate_detect_language]
+    // TODO(developer): Uncomment these lines.
+    // import com.google.cloud.translate.*;
+    // Translate translate = TranslateOptions.getDefaultInstance().getService();
+
+    List texts = new LinkedList<>();
+    texts.add("Hello, World!");
+    texts.add("¡Hola Mundo!");
+    List detections = translate.detect(texts);
+
+    System.out.println("Language(s) detected:");
+    for (Detection detection : detections) {
+      System.out.printf("\t%s\n", detection);
+    }
+    // [END translate_detect_language]
+
     Detection detection = detections.get(0);
     assertEquals("en", detection.getLanguage());
     detection = detections.get(1);
@@ -96,13 +147,21 @@ public void testDetectLanguageOfTextList() {
 
   @Test
   public void testDetectLanguageOfText() {
-    Detection detection = translateSnippets.detectLanguageOfText();
+    // SNIPPET translate_detect_language_string
+    Detection detection = translate.detect("Hello, World!");
+    // SNIPPET translate_detect_language_string
     assertEquals("en", detection.getLanguage());
   }
 
   @Test
   public void testTranslateTextList() {
-    List translations = translateSnippets.translateTexts();
+    // SNIPPET translateTexts
+    List texts = new LinkedList<>();
+    texts.add("Hello, World!");
+    texts.add("¡Hola Mundo!");
+    List translations = translate.translate(texts);
+    // SNIPPET translateTexts
+
     Translation translation = translations.get(0);
     assertEquals("Hello, World!", translation.getTranslatedText());
     assertEquals("en", translation.getSourceLanguage());
@@ -111,16 +170,49 @@ public void testTranslateTextList() {
     assertEquals("es", translation.getSourceLanguage());
   }
 
+  @Test
+  public void testTranslateTextListWithOptions() {
+    // SNIPPET translateTextsWithOptions
+    List texts = new LinkedList<>();
+    texts.add("¡Hola Mundo!");
+    List translations = translate.translate(
+        texts,
+        Translate.TranslateOption.sourceLanguage("es"),
+        Translate.TranslateOption.targetLanguage("de"));
+    // SNIPPET translateTextsWithOptions
+    Translation translation = translations.get(0);
+    assertEquals("Hallo Welt!", translation.getTranslatedText());
+    assertEquals("es", translation.getSourceLanguage());
+  }
+
   @Test
   public void testTranslateText() {
-    Translation translation = translateSnippets.translateText();
+    // [START translate_translate_text]
+    // TODO(developer): Uncomment these lines.
+    // import com.google.cloud.translate.*;
+    // Translate translate = TranslateOptions.getDefaultInstance().getService();
+
+    Translation translation = translate.translate("¡Hola Mundo!");
+    System.out.printf("Translated Text:\n\t%s\n", translation.getTranslatedText());
+    // [END translate_translate_text]
     assertEquals("Hello World!", translation.getTranslatedText());
     assertEquals("es", translation.getSourceLanguage());
   }
 
   @Test
-  public void testTranslateTextWithOptions() {
-    Translation translation = translateSnippets.translateTextWithOptions();
+  public void testTranslateTextWithModel() {
+    // [START translate_text_with_model]
+    Translation translation = translate.translate(
+        "Hola Mundo!",
+        Translate.TranslateOption.sourceLanguage("es"),
+        Translate.TranslateOption.targetLanguage("de"),
+        // Use "base" for standard edition, "nmt" for the premium model.
+        Translate.TranslateOption.model("nmt"));
+
+    System.out.printf(
+        "TranslatedText:\nText: %s\n",
+        translation.getTranslatedText());
+    // [END translate_text_with_model]
     assertEquals("Hallo Welt!", translation.getTranslatedText());
     assertEquals("es", translation.getSourceLanguage());
   }
diff --git a/utilities/snippets.go b/utilities/snippets.go
index 5a9c66204c37..c3215ba830d6 100644
--- a/utilities/snippets.go
+++ b/utilities/snippets.go
@@ -24,6 +24,9 @@ import (
 	"path/filepath"
 	"runtime/pprof"
 	"strings"
+
+	"github.com/kr/text"
+	"github.com/lithammer/dedent"
 )
 
 func init() {
@@ -127,10 +130,10 @@ func getCloud(file, txt string, snip map[string]string) error {
 			key := fmt.Sprintf("", tag)
 			snipTxt := strings.Trim(txt[:p], "\n\r")
 			if _, exist := snip[key]; exist {
-				snip[key] = strings.Join([]string{snip[key], snipTxt}, "")
+				snip[key] = strings.Join([]string{snip[key], text.Indent(dedent.Dedent(snipTxt), " ")}, "")
 			}
 
-			snip[key] = snipTxt
+			snip[key] = text.Indent(dedent.Dedent(snipTxt), " ")
 			txt = txt[p+len(endTag):]
 		} else {
 			return fmt.Errorf("[START %s]:%d snippet %q not closed", file, lineNum(ftxt, txt), tag)
@@ -166,7 +169,7 @@ func getSnip(file, txt string, snip map[string]string) error {
 				return fmt.Errorf("%s:%d snippet %q has already been defined", file, lineNum(ftxt, txt), key)
 			}
 
-			snip[key] = strings.Trim(txt[:p], "\n\r")
+			snip[key] = text.Indent(dedent.Dedent(strings.Trim(txt[:p], "\n\r")), " ")
 			txt = txt[p+len(snipPrefix):]
 		} else {
 			return fmt.Errorf("%s:%d snippet %q not closed", file, lineNum(ftxt, txt), key)