Process markdown cloud links for PHP

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

@@ -0,0 +1,101 @@
+/* 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.common.base.Function;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/** A collection of static helper methods for reformatting comments. */
+public class CommentReformatting {
+
+  public static String CLOUD_URL_PREFIX = "https://cloud.google.com";
+
+  private CommentReformatting() {}
+
+  public static String reformatAbsoluteMarkdownLinks(String comment, String linkFormat) {
+    return reformatPattern(
+        comment, CommentPatterns.ABSOLUTE_LINK_PATTERN, reformatLinkFunction(linkFormat, ""));
+  }
+
+  public static String reformatCloudMarkdownLinks(String comment, String linkFormat) {
+    return reformatPattern(
+        comment,
+        CommentPatterns.CLOUD_LINK_PATTERN,
+        reformatLinkFunction(linkFormat, CLOUD_URL_PREFIX));
+  }
+
+  public static String reformatPattern(
+      String comment, Pattern pattern, Function<Matcher, String> replacementFunction) {
+    StringBuffer sb = new StringBuffer();
+    Matcher m = pattern.matcher(comment);
+    if (!m.find()) {
+      return comment;
+    }
+    do {
+      m.appendReplacement(sb, replacementFunction.apply(m));
+    } while (m.find());
+    m.appendTail(sb);
+    return sb.toString();
+  }
+
+  public static Formatter of(String comment) {
+    return new Formatter(comment);
+  }
+
+  /**
+   * The Formatter object allows the static methods in CommentReformatting to be used via a fluent
+   * interface.
+   */
+  public static class Formatter {
+    private String comment;
+
+    private Formatter(String comment) {
+      this.comment = comment;
+    }
+
+    public Formatter reformat(Pattern pattern, Function<Matcher, String> replacementFunction) {
+      comment = CommentReformatting.reformatPattern(comment, pattern, replacementFunction);
+      return this;
+    }
+
+    public Formatter reformatAbsoluteMarkdownLinks(String linkFormat) {
+      comment = CommentReformatting.reformatAbsoluteMarkdownLinks(comment, linkFormat);
+      return this;
+    }
+
+    public Formatter reformatCloudMarkdownLinks(String linkFormat) {
+      comment = CommentReformatting.reformatCloudMarkdownLinks(comment, linkFormat);
+      return this;
+    }
+
+    @Override
+    public String toString() {
+      return comment;
+    }
+  }
+
+  private static Function<Matcher, String> reformatLinkFunction(
+      final String linkFormat, final String urlPrefix) {
+    return new Function<Matcher, String>() {
+      @Override
+      public String apply(Matcher matcher) {
+        String url = urlPrefix + matcher.group(2);
+        return Matcher.quoteReplacement(String.format(linkFormat, matcher.group(1), url));
+      }
+    };
+  }
+}

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

@@ -16,48 +16,30 @@
 
 import com.google.api.codegen.CommentPatterns;
 import com.google.api.codegen.util.CommentReformatter;
+import com.google.api.codegen.util.CommentReformatting;
 import com.google.api.tools.framework.model.ProtoElement;
 import com.google.api.tools.framework.model.ProtoFile;
+import com.google.common.base.Function;
 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();
-  }
+  private static Function<Matcher, String> PROTO_TO_JS_DOC =
+      new Function<Matcher, String>() {
+        @Override
+        public String apply(Matcher matcher) {
+          return Matcher.quoteReplacement(String.format("{@link %s}", matcher.group(1)));
+        }
+      };
 
-  /** 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();
+  @Override
+  public String reformat(String comment) {
+    return CommentReformatting.of(comment)
+        .reformat(CommentPatterns.PROTO_LINK_PATTERN, PROTO_TO_JS_DOC)
+        .reformatCloudMarkdownLinks("[%s](%s)")
+        .toString()
+        .trim();
   }
 
   public String getLinkedElementName(ProtoElement element) {

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

@@ -15,6 +15,7 @@
 package com.google.api.codegen.util.php;
 
 import com.google.api.codegen.util.CommentReformatter;
+import com.google.api.codegen.util.CommentReformatting;
 import com.google.common.escape.Escaper;
 import com.google.common.escape.Escapers;
 
@@ -25,6 +26,8 @@ public class PhpCommentReformatter implements CommentReformatter {
 
   @Override
   public String reformat(String comment) {
-    return PHP_ESCAPER.escape(comment).trim();
+    comment = PHP_ESCAPER.escape(comment);
+    comment = CommentReformatting.reformatCloudMarkdownLinks(comment, "[%s](%s)");
+    return comment.trim();
   }
 }

src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java

@@ -16,13 +16,30 @@
 
 import com.google.api.codegen.CommentPatterns;
 import com.google.api.codegen.util.CommentReformatter;
+import com.google.api.codegen.util.CommentReformatting;
+import com.google.common.base.Function;
 import com.google.common.base.Splitter;
 import com.google.common.base.Strings;
 import java.util.regex.Matcher;
 
 public class RubyCommentReformatter implements CommentReformatter {
   private static final String BULLET = "* ";
 
+  private static Function<Matcher, String> PROTO_TO_RUBY_DOC =
+      new Function<Matcher, String>() {
+        @Override
+        public String apply(Matcher matcher) {
+          return Matcher.quoteReplacement(protoToRubyDoc(matcher.group(1)));
+        }
+      };
+  private static Function<Matcher, String> HEADLINE_REPLACE =
+      new Function<Matcher, String>() {
+        @Override
+        public String apply(Matcher matcher) {
+          return matcher.group().replace("#", "=");
+        }
+      };
+
   @Override
   public String reformat(String comment) {
     StringBuffer sb = new StringBuffer();
@@ -56,30 +73,15 @@ public String reformat(String comment) {
 
   private String applyTransformations(String line) {
     line = CommentPatterns.BACK_QUOTE_PATTERN.matcher(line).replaceAll("+");
-    line = reformatProtoMarkdownLinks(line);
-    line = reformatCloudMarkdownLinks(line);
-    line = reformatAbsoluteMarkdownLinks(line);
-    line = reformatHeadline(line);
-    return line;
-  }
-
-  /** Returns a string with all proto markdown links formatted to RDoc 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", protoToRubyDoc(m.group(1)))));
-    } while (m.find());
-    m.appendTail(sb);
-    return sb.toString();
+    return CommentReformatting.of(line)
+        .reformat(CommentPatterns.PROTO_LINK_PATTERN, PROTO_TO_RUBY_DOC)
+        .reformatCloudMarkdownLinks("{%s}[%s]")
+        .reformatAbsoluteMarkdownLinks("{%s}[%s]")
+        .reformat(CommentPatterns.HEADLINE_PATTERN, HEADLINE_REPLACE)
+        .toString();
   }
 
-  private String protoToRubyDoc(String comment) {
+  private static String protoToRubyDoc(String comment) {
     boolean messageFound = false;
     boolean isFirstSegment = true;
     String result = "";
@@ -100,49 +102,4 @@ private String protoToRubyDoc(String comment) {
     }
     return result;
   }
-
-  /** Returns a string with all cloud markdown links formatted to RDoc 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();
-  }
-
-  /** Returns a string with all absolute markdown links formatted to RDoc 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();
-  }
-
-  private String reformatHeadline(String comment) {
-    StringBuffer sb = new StringBuffer();
-    Matcher m = CommentPatterns.HEADLINE_PATTERN.matcher(comment);
-    if (!m.find()) {
-      return comment;
-    }
-    do {
-      m.appendReplacement(sb, m.group().replace("#", "="));
-    } while (m.find());
-    m.appendTail(sb);
-    return sb.toString();
-  }
 }

src/test/java/com/google/api/codegen/testdata/php_main_library.baseline

@@ -91,7 +91,7 @@ use google\tagger\v1\LabelerGrpcClient;
  * - Each Shelf has a collection of [Book][google.example.library.v1.Book]
  *   resources, named `bookShelves/*/books/*`
  *
- * Check out [cloud docs!](/library/example/link).
+ * Check out [cloud docs!](https://cloud.google.com/library/example/link).
  * This is [not a cloud link](http://www.google.com).
  *
  * Service comment may include special characters: <>&"`'&#64;.