Process markdown cloud links for PHP

src/main/java/com/google/api/codegen/util/CommentTransformer.java

@@ -0,0 +1,69 @@
+/* Copyright 2017 Google Inc
+ *
+ * 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.api.codegen.util;
+
+import com.google.common.base.Function;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+public class CommentTransformer {
+
+  public static String CLOUD_URL_PREFIX = "https://cloud.google.com";
+
+  private String comment;
+
+  private CommentTransformer(String comment) {
+    this.comment = comment;
+  }
+
+  public static CommentTransformer of(String comment) {
+    return new CommentTransformer(comment);
+  }
+
+  public CommentTransformer replace(Pattern pattern, String replacement) {
+    comment = pattern.matcher(comment).replaceAll(replacement);
+    return this;
+  }
+
+  public CommentTransformer transform(Transformation transformation) {
+    comment = transformation.apply(comment);
+    return this;
+  }
+
+  @Override
+  public String toString() {
+    return comment;
+  }
+
+  public static class Transformation {
+    private Pattern pattern;
+    private Function<Matcher, String> replacementFunction;
+
+    public Transformation(Pattern pattern, Function<Matcher, String> replacementFunction) {
+      this.pattern = pattern;
+      this.replacementFunction = replacementFunction;
+    }
+
+    public String apply(String comment) {
+      StringBuffer sb = new StringBuffer();
+      Matcher m = pattern.matcher(comment);
+      while (m.find()) {
+        m.appendReplacement(sb, replacementFunction.apply(m));
+      }
+      m.appendTail(sb);
+      return sb.toString();
+    }
+  }
+}

src/main/java/com/google/api/codegen/util/ProtoLinkPattern.java

@@ -0,0 +1,53 @@
+/* Copyright 2017 Google Inc
+ *
+ * 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.api.codegen.util;
+
+import com.google.api.codegen.CommentPatterns;
+import com.google.api.codegen.util.CommentTransformer.Transformation;
+import com.google.common.base.Function;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * An enumeration of link formats found in proto files. Each element of the enumeration is
+ * associated with a {@link Pattern} object that must contain exactly two groups matching the link
+ * title and link url.
+ */
+public enum ProtoLinkPattern {
+  ABSOLUTE(CommentPatterns.ABSOLUTE_LINK_PATTERN, ""),
+  CLOUD(CommentPatterns.CLOUD_LINK_PATTERN, CommentTransformer.CLOUD_URL_PREFIX),
+  PROTO(CommentPatterns.PROTO_LINK_PATTERN, "");
+
+  private Pattern pattern;
+  private String urlPrefix;
+
+  ProtoLinkPattern(Pattern pattern, String urlPrefix) {
+    this.pattern = pattern;
+    this.urlPrefix = urlPrefix;
+  }
+
+  public Transformation createTransformation(final String linkFormat) {
+    return new Transformation(
+        pattern,
+        new Function<Matcher, String>() {
+          @Override
+          public String apply(Matcher matcher) {
+            String title = matcher.group(1);
+            String url = urlPrefix + matcher.group(2);
+            return Matcher.quoteReplacement(String.format(linkFormat, title, url));
+          }
+        });
+  }
+}

src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java

@@ -14,50 +14,22 @@
  */
 package com.google.api.codegen.util.js;
 
-import com.google.api.codegen.CommentPatterns;
 import com.google.api.codegen.util.CommentReformatter;
+import com.google.api.codegen.util.CommentTransformer;
+import com.google.api.codegen.util.ProtoLinkPattern;
 import com.google.api.tools.framework.model.ProtoElement;
 import com.google.api.tools.framework.model.ProtoFile;
 import com.google.common.collect.ImmutableSet;
-import java.util.regex.Matcher;
 
 public class JSCommentReformatter implements CommentReformatter {
+
   @Override
   public String reformat(String comment) {
-    comment = reformatProtoMarkdownLinks(comment);
-    comment = reformatCloudMarkdownLinks(comment);
-    return comment.trim();
-  }
-
-  /** Returns a string with all proto markdown links formatted to JSDoc style. */
-  private String reformatProtoMarkdownLinks(String comment) {
-    StringBuffer sb = new StringBuffer();
-    Matcher m = CommentPatterns.PROTO_LINK_PATTERN.matcher(comment);
-    if (!m.find()) {
-      return comment;
-    }
-    do {
-      // proto display name may contain '$' which needs to be escaped using Matcher.quoteReplacement
-      m.appendReplacement(sb, Matcher.quoteReplacement(String.format("{@link %s}", m.group(1))));
-    } while (m.find());
-    m.appendTail(sb);
-    return sb.toString();
-  }
-
-  /** Returns a string with all cloud markdown links formatted to JSDoc style. */
-  private String reformatCloudMarkdownLinks(String comment) {
-    StringBuffer sb = new StringBuffer();
-    Matcher m = CommentPatterns.CLOUD_LINK_PATTERN.matcher(comment);
-    if (!m.find()) {
-      return comment;
-    }
-    do {
-      String url = "https://cloud.google.com" + m.group(2);
-      // cloud markdown links may contain '$' which needs to be escaped using Matcher.quoteReplacement
-      m.appendReplacement(sb, Matcher.quoteReplacement(String.format("[%s](%s)", m.group(1), url)));
-    } while (m.find());
-    m.appendTail(sb);
-    return sb.toString();
+    return CommentTransformer.of(comment)
+        .transform(ProtoLinkPattern.PROTO.createTransformation("{@link %s}"))
+        .transform(ProtoLinkPattern.CLOUD.createTransformation("[%s](%s)"))
+        .toString()
+        .trim();
   }
 
   public String getLinkedElementName(ProtoElement element) {

src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java

@@ -15,16 +15,21 @@
 package com.google.api.codegen.util.php;
 
 import com.google.api.codegen.util.CommentReformatter;
-import com.google.common.escape.Escaper;
-import com.google.common.escape.Escapers;
+import com.google.api.codegen.util.CommentTransformer;
+import com.google.api.codegen.util.ProtoLinkPattern;
+import java.util.regex.Pattern;
 
 public class PhpCommentReformatter implements CommentReformatter {
-  /** Escaper for formatting PHP doc strings. */
-  private static final Escaper PHP_ESCAPER =
-      Escapers.builder().addEscape('*', "*").addEscape('@', "@").build();
+  public static final Pattern ASTERISK_PATTERN = Pattern.compile("\\*");
+  public static final Pattern AMPERSAND_PATTERN = Pattern.compile("@");
 
   @Override
   public String reformat(String comment) {
-    return PHP_ESCAPER.escape(comment).trim();
+    return CommentTransformer.of(comment)
+        .replace(ASTERISK_PATTERN, "*")
+        .replace(AMPERSAND_PATTERN, "@")
+        .transform(ProtoLinkPattern.CLOUD.createTransformation("[%s](%s)"))
+        .toString()
+        .trim();
   }
 }

src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java

@@ -16,10 +16,12 @@
 
 import com.google.api.codegen.CommentPatterns;
 import com.google.api.codegen.util.CommentReformatter;
+import com.google.api.codegen.util.CommentTransformer;
+import com.google.api.codegen.util.ProtoLinkPattern;
 import com.google.common.base.Splitter;
-import java.util.regex.Matcher;
 
 public class PythonCommentReformatter implements CommentReformatter {
+
   @Override
   public String reformat(String comment) {
     boolean inCodeBlock = false;
@@ -53,58 +55,11 @@ public String reformat(String comment) {
   }
 
   private String applyTransformations(String line) {
-    line = CommentPatterns.BACK_QUOTE_PATTERN.matcher(line).replaceAll("``");
-    line = reformatProtoMarkdownLinks(line);
-    line = reformatAbsoluteMarkdownLinks(line);
-    return reformatCloudMarkdownLinks(line);
-  }
-
-  /** Returns a string with all proto markdown links formatted to Sphinx style. */
-  private String reformatProtoMarkdownLinks(String comment) {
-    StringBuffer sb = new StringBuffer();
-    Matcher m = CommentPatterns.PROTO_LINK_PATTERN.matcher(comment);
-    if (!m.find()) {
-      return comment;
-    }
-    do {
-      // proto display name may contain '$' which needs to be escaped using Matcher.quoteReplacement
-      m.appendReplacement(sb, Matcher.quoteReplacement(String.format("``%s``", m.group(1))));
-    } while (m.find());
-    m.appendTail(sb);
-    return sb.toString();
-  }
-
-  /** Returns a string with all absolute markdown links formatted to Sphinx style. */
-  private String reformatAbsoluteMarkdownLinks(String comment) {
-    StringBuffer sb = new StringBuffer();
-    Matcher m = CommentPatterns.ABSOLUTE_LINK_PATTERN.matcher(comment);
-    if (!m.find()) {
-      return comment;
-    }
-    do {
-      // absolute markdown links may contain '$' which needs to be escaped using Matcher.quoteReplacement
-      m.appendReplacement(
-          sb, Matcher.quoteReplacement(String.format("`%s <%s>`_", m.group(1), m.group(2))));
-    } while (m.find());
-    m.appendTail(sb);
-    return sb.toString();
-  }
-
-  /** Returns a string with all cloud markdown links formatted to Sphinx style. */
-  private String reformatCloudMarkdownLinks(String comment) {
-    StringBuffer sb = new StringBuffer();
-    Matcher m = CommentPatterns.CLOUD_LINK_PATTERN.matcher(comment);
-    if (!m.find()) {
-      return comment;
-    }
-    do {
-      // cloud markdown links may contain '$' which needs to be escaped using Matcher.quoteReplacement
-      m.appendReplacement(
-          sb,
-          Matcher.quoteReplacement(
-              String.format("`%s <https://cloud.google.com%s>`_", m.group(1), m.group(2))));
-    } while (m.find());
-    m.appendTail(sb);
-    return sb.toString();
+    return CommentTransformer.of(line)
+        .replace(CommentPatterns.BACK_QUOTE_PATTERN, "``")
+        .transform(ProtoLinkPattern.PROTO.createTransformation("``%s``"))
+        .transform(ProtoLinkPattern.ABSOLUTE.createTransformation("`%s <%s>`_"))
+        .transform(ProtoLinkPattern.CLOUD.createTransformation("`%s <%s>`_"))
+        .toString();
   }
 }