From 54fa70aa5fedbe12fe6b4e865abd0ad607865f6f Mon Sep 17 00:00:00 2001 From: Michael Bausor Date: Fri, 3 Mar 2017 11:03:19 -0800 Subject: [PATCH 01/12] Process markdown cloud links for PHP --- .../util/php/PhpCommentReformatter.java | 22 ++++++++++++++++++- .../testdata/php_main_library.baseline | 2 +- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java index 72845a1708..973d1e40c2 100644 --- a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java @@ -14,9 +14,11 @@ */ package com.google.api.codegen.util.php; +import com.google.api.codegen.CommentPatterns; import com.google.api.codegen.util.CommentReformatter; import com.google.common.escape.Escaper; import com.google.common.escape.Escapers; +import java.util.regex.Matcher; public class PhpCommentReformatter implements CommentReformatter { /** Escaper for formatting PHP doc strings. */ @@ -25,6 +27,24 @@ public class PhpCommentReformatter implements CommentReformatter { @Override public String reformat(String comment) { - return PHP_ESCAPER.escape(comment).trim(); + comment = PHP_ESCAPER.escape(comment); + comment = reformatCloudMarkdownLinks(comment); + return comment.trim(); + } + + /** 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(); } } diff --git a/src/test/java/com/google/api/codegen/testdata/php_main_library.baseline b/src/test/java/com/google/api/codegen/testdata/php_main_library.baseline index d127734e17..26c87d8ebd 100644 --- a/src/test/java/com/google/api/codegen/testdata/php_main_library.baseline +++ b/src/test/java/com/google/api/codegen/testdata/php_main_library.baseline @@ -86,7 +86,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: <>&"`'@. From 834373d83ee4692574a338797c896e6511a6ec7f Mon Sep 17 00:00:00 2001 From: Michael Bausor Date: Wed, 3 May 2017 08:19:21 -0700 Subject: [PATCH 02/12] Add comment reformatter to share code --- .../api/codegen/util/CommentReformatting.java | 61 ++++++++++++ .../codegen/util/js/JSCommentReformatter.java | 48 +++------- .../util/php/PhpCommentReformatter.java | 21 +--- .../util/ruby/RubyCommentReformatter.java | 95 ++++++------------- 4 files changed, 107 insertions(+), 118 deletions(-) create mode 100644 src/main/java/com/google/api/codegen/util/CommentReformatting.java diff --git a/src/main/java/com/google/api/codegen/util/CommentReformatting.java b/src/main/java/com/google/api/codegen/util/CommentReformatting.java new file mode 100644 index 0000000000..032765fbbb --- /dev/null +++ b/src/main/java/com/google/api/codegen/util/CommentReformatting.java @@ -0,0 +1,61 @@ +/* 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; + +public class CommentReformatting { + 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, "https://cloud.google.com")); + } + + public static String reformatPattern( + String comment, Pattern pattern, Function 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(); + } + + private static Function reformatLinkFunction( + final String linkFormat, final String urlPrefix) { + return new Function() { + @Override + public String apply(Matcher matcher) { + String url = urlPrefix + matcher.group(2); + return Matcher.quoteReplacement(String.format(linkFormat, matcher.group(1), url)); + } + }; + } +} diff --git a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java index 9907944126..8eaec0a78e 100644 --- a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java @@ -16,44 +16,26 @@ 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 java.util.regex.Matcher; public class JSCommentReformatter implements CommentReformatter { + + private static Function PROTO_TO_JS_DOC = + new Function() { + @Override + public String apply(Matcher matcher) { + return Matcher.quoteReplacement(String.format("{@link %s}", matcher.group(1))); + } + }; + @Override public String reformat(String comment) { - comment = reformatProtoMarkdownLinks(comment); - comment = reformatCloudMarkdownLinks(comment); + comment = + CommentReformatting.reformatPattern( + comment, CommentPatterns.PROTO_LINK_PATTERN, PROTO_TO_JS_DOC); + comment = CommentReformatting.reformatCloudMarkdownLinks(comment, "[%s](%s)"); 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(); - } } diff --git a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java index 973d1e40c2..81943fea66 100644 --- a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java @@ -14,11 +14,10 @@ */ package com.google.api.codegen.util.php; -import com.google.api.codegen.CommentPatterns; 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; -import java.util.regex.Matcher; public class PhpCommentReformatter implements CommentReformatter { /** Escaper for formatting PHP doc strings. */ @@ -28,23 +27,7 @@ public class PhpCommentReformatter implements CommentReformatter { @Override public String reformat(String comment) { comment = PHP_ESCAPER.escape(comment); - comment = reformatCloudMarkdownLinks(comment); + comment = CommentReformatting.reformatCloudMarkdownLinks(comment, "[%s](%s)"); return comment.trim(); } - - /** 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(); - } } diff --git a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java index 6ff0e26c56..66e5e30540 100644 --- a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java @@ -16,37 +16,45 @@ 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 java.util.regex.Matcher; +import javax.annotation.Nullable; public class RubyCommentReformatter implements CommentReformatter { + + private static Function PROTO_TO_RUBY_DOC = + new Function() { + @Override + public String apply(Matcher matcher) { + return Matcher.quoteReplacement(protoToRubyDoc(matcher.group(1))); + } + }; + private static Function HEADLINE_REPLACE = + new Function() { + @Nullable + @Override + public String apply(@Nullable Matcher matcher) { + return matcher.group().replace("#", "="); + } + }; + @Override public String reformat(String comment) { comment = CommentPatterns.BACK_QUOTE_PATTERN.matcher(comment).replaceAll("+"); - comment = reformatProtoMarkdownLinks(comment); - comment = reformatCloudMarkdownLinks(comment); - comment = reformatAbsoluteMarkdownLinks(comment); - comment = reformatHeadline(comment); + comment = + CommentReformatting.reformatPattern( + comment, CommentPatterns.PROTO_LINK_PATTERN, PROTO_TO_RUBY_DOC); + comment = CommentReformatting.reformatCloudMarkdownLinks(comment, "{%s}[%s]"); + comment = CommentReformatting.reformatAbsoluteMarkdownLinks(comment, "{%s}[%s]"); + comment = + CommentReformatting.reformatPattern( + comment, CommentPatterns.HEADLINE_PATTERN, HEADLINE_REPLACE); return comment.trim(); } - /** 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(); - } - - private String protoToRubyDoc(String comment) { + private static String protoToRubyDoc(String comment) { boolean messageFound = false; boolean isFirstSegment = true; String result = ""; @@ -67,49 +75,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(); - } } From cea4eeb4c660b47ed24150c9d78326066e3ab11c Mon Sep 17 00:00:00 2001 From: Michael Bausor Date: Wed, 3 May 2017 08:39:05 -0700 Subject: [PATCH 03/12] Add fluent interface --- .../api/codegen/util/CommentReformatting.java | 42 ++++++++++++++++++- .../codegen/util/js/JSCommentReformatter.java | 10 ++--- .../util/ruby/RubyCommentReformatter.java | 16 ++++--- 3 files changed, 53 insertions(+), 15 deletions(-) diff --git a/src/main/java/com/google/api/codegen/util/CommentReformatting.java b/src/main/java/com/google/api/codegen/util/CommentReformatting.java index 032765fbbb..69eda30b38 100644 --- a/src/main/java/com/google/api/codegen/util/CommentReformatting.java +++ b/src/main/java/com/google/api/codegen/util/CommentReformatting.java @@ -19,7 +19,11 @@ 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) { @@ -31,7 +35,7 @@ public static String reformatCloudMarkdownLinks(String comment, String linkForma return reformatPattern( comment, CommentPatterns.CLOUD_LINK_PATTERN, - reformatLinkFunction(linkFormat, "https://cloud.google.com")); + reformatLinkFunction(linkFormat, CLOUD_URL_PREFIX)); } public static String reformatPattern( @@ -48,6 +52,42 @@ public static String reformatPattern( 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 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 reformatLinkFunction( final String linkFormat, final String urlPrefix) { return new Function() { diff --git a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java index 8eaec0a78e..fb047e135d 100644 --- a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java @@ -32,10 +32,10 @@ public String apply(Matcher matcher) { @Override public String reformat(String comment) { - comment = - CommentReformatting.reformatPattern( - comment, CommentPatterns.PROTO_LINK_PATTERN, PROTO_TO_JS_DOC); - comment = CommentReformatting.reformatCloudMarkdownLinks(comment, "[%s](%s)"); - return comment.trim(); + return CommentReformatting.of(comment) + .reformat(CommentPatterns.PROTO_LINK_PATTERN, PROTO_TO_JS_DOC) + .reformatCloudMarkdownLinks("[%s](%s)") + .toString() + .trim(); } } diff --git a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java index 66e5e30540..99359493d8 100644 --- a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java @@ -43,15 +43,13 @@ public String apply(@Nullable Matcher matcher) { @Override public String reformat(String comment) { comment = CommentPatterns.BACK_QUOTE_PATTERN.matcher(comment).replaceAll("+"); - comment = - CommentReformatting.reformatPattern( - comment, CommentPatterns.PROTO_LINK_PATTERN, PROTO_TO_RUBY_DOC); - comment = CommentReformatting.reformatCloudMarkdownLinks(comment, "{%s}[%s]"); - comment = CommentReformatting.reformatAbsoluteMarkdownLinks(comment, "{%s}[%s]"); - comment = - CommentReformatting.reformatPattern( - comment, CommentPatterns.HEADLINE_PATTERN, HEADLINE_REPLACE); - return comment.trim(); + return CommentReformatting.of(comment) + .reformat(CommentPatterns.PROTO_LINK_PATTERN, PROTO_TO_RUBY_DOC) + .reformatCloudMarkdownLinks("{%s}[%s]") + .reformatAbsoluteMarkdownLinks("{%s}[%s]") + .reformat(CommentPatterns.HEADLINE_PATTERN, HEADLINE_REPLACE) + .toString() + .trim(); } private static String protoToRubyDoc(String comment) { From 1b901db458056e13477ccb5cfa0f00764f99323c Mon Sep 17 00:00:00 2001 From: Michael Bausor Date: Wed, 3 May 2017 09:09:25 -0700 Subject: [PATCH 04/12] Remove trim --- .../google/api/codegen/util/ruby/RubyCommentReformatter.java | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java index 611615c957..04f471554b 100644 --- a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java @@ -78,8 +78,7 @@ private String applyTransformations(String line) { .reformatCloudMarkdownLinks("{%s}[%s]") .reformatAbsoluteMarkdownLinks("{%s}[%s]") .reformat(CommentPatterns.HEADLINE_PATTERN, HEADLINE_REPLACE) - .toString() - .trim(); + .toString(); } private static String protoToRubyDoc(String comment) { From 7dba1e4dcf2a56ec8d1f5f647e0faa6ce00d8141 Mon Sep 17 00:00:00 2001 From: Michael Bausor Date: Tue, 9 May 2017 10:52:40 -0700 Subject: [PATCH 05/12] Switch to fluent interface only, support python --- .../api/codegen/transformer/SurfaceNamer.java | 6 +- .../api/codegen/util/CommentReformatter.java | 78 +++++++++++++- .../api/codegen/util/CommentReformatting.java | 101 ------------------ .../util/LanguageCommentReformatter.java | 20 ++++ .../util/PassThroughCommentReformatter.java | 2 +- .../util/csharp/CSharpCommentReformatter.java | 4 +- .../util/java/JavaCommentReformatter.java | 4 +- .../codegen/util/js/JSCommentReformatter.java | 6 +- .../util/php/PhpCommentReformatter.java | 21 ++-- .../util/py/PythonCommentReformatter.java | 67 +++--------- .../util/ruby/RubyCommentReformatter.java | 8 +- 11 files changed, 134 insertions(+), 183 deletions(-) delete mode 100644 src/main/java/com/google/api/codegen/util/CommentReformatting.java create mode 100644 src/main/java/com/google/api/codegen/util/LanguageCommentReformatter.java diff --git a/src/main/java/com/google/api/codegen/transformer/SurfaceNamer.java b/src/main/java/com/google/api/codegen/transformer/SurfaceNamer.java index 37283252e5..07ce7304d6 100644 --- a/src/main/java/com/google/api/codegen/transformer/SurfaceNamer.java +++ b/src/main/java/com/google/api/codegen/transformer/SurfaceNamer.java @@ -26,8 +26,8 @@ import com.google.api.codegen.config.ResourceNameType; import com.google.api.codegen.config.SingleResourceNameConfig; import com.google.api.codegen.config.VisibilityConfig; -import com.google.api.codegen.util.CommentReformatter; import com.google.api.codegen.util.CommonRenderingUtil; +import com.google.api.codegen.util.LanguageCommentReformatter; import com.google.api.codegen.util.Name; import com.google.api.codegen.util.NameFormatter; import com.google.api.codegen.util.NameFormatterDelegator; @@ -64,14 +64,14 @@ public class SurfaceNamer extends NameFormatterDelegator { private final ModelTypeFormatter modelTypeFormatter; private final TypeNameConverter typeNameConverter; - private final CommentReformatter commentReformatter; + private final LanguageCommentReformatter commentReformatter; private final String packageName; public SurfaceNamer( NameFormatter languageNamer, ModelTypeFormatter modelTypeFormatter, TypeNameConverter typeNameConverter, - CommentReformatter commentReformatter, + LanguageCommentReformatter commentReformatter, String packageName) { super(languageNamer); this.modelTypeFormatter = modelTypeFormatter; diff --git a/src/main/java/com/google/api/codegen/util/CommentReformatter.java b/src/main/java/com/google/api/codegen/util/CommentReformatter.java index 4f43a0c9a4..759b7c182a 100644 --- a/src/main/java/com/google/api/codegen/util/CommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/CommentReformatter.java @@ -14,7 +14,79 @@ */ package com.google.api.codegen.util; -public interface CommentReformatter { - /** Reformats the given comment to match a language comment format */ - String reformat(String comment); +import com.google.api.codegen.CommentPatterns; +import com.google.common.base.Function; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +public class CommentReformatter { + + public static String CLOUD_URL_PREFIX = "https://cloud.google.com"; + + private String comment; + + private CommentReformatter(String comment) { + this.comment = comment; + } + + public static CommentReformatter of(String comment) { + return new CommentReformatter(comment); + } + + public CommentReformatter reformat( + Pattern pattern, Function replacementFunction) { + comment = reformatPattern(comment, pattern, replacementFunction); + return this; + } + + public CommentReformatter replace(Pattern pattern, String replacement) { + comment = pattern.matcher(comment).replaceAll(replacement); + return this; + } + + public CommentReformatter reformatAbsoluteMarkdownLinks(String linkFormat) { + comment = + reformatPattern( + comment, CommentPatterns.ABSOLUTE_LINK_PATTERN, reformatLinkFunction(linkFormat, "")); + return this; + } + + public CommentReformatter reformatCloudMarkdownLinks(String linkFormat) { + comment = + reformatPattern( + comment, + CommentPatterns.CLOUD_LINK_PATTERN, + reformatLinkFunction(linkFormat, CLOUD_URL_PREFIX)); + return this; + } + + @Override + public String toString() { + return comment; + } + + public static Function reformatLinkFunction( + final String linkFormat, final String urlPrefix) { + return new Function() { + @Override + public String apply(Matcher matcher) { + String url = urlPrefix + matcher.group(2); + return Matcher.quoteReplacement(String.format(linkFormat, matcher.group(1), url)); + } + }; + } + + private static String reformatPattern( + String comment, Pattern pattern, Function 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(); + } } diff --git a/src/main/java/com/google/api/codegen/util/CommentReformatting.java b/src/main/java/com/google/api/codegen/util/CommentReformatting.java deleted file mode 100644 index 69eda30b38..0000000000 --- a/src/main/java/com/google/api/codegen/util/CommentReformatting.java +++ /dev/null @@ -1,101 +0,0 @@ -/* 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 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 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 reformatLinkFunction( - final String linkFormat, final String urlPrefix) { - return new Function() { - @Override - public String apply(Matcher matcher) { - String url = urlPrefix + matcher.group(2); - return Matcher.quoteReplacement(String.format(linkFormat, matcher.group(1), url)); - } - }; - } -} diff --git a/src/main/java/com/google/api/codegen/util/LanguageCommentReformatter.java b/src/main/java/com/google/api/codegen/util/LanguageCommentReformatter.java new file mode 100644 index 0000000000..3e7ed00b3b --- /dev/null +++ b/src/main/java/com/google/api/codegen/util/LanguageCommentReformatter.java @@ -0,0 +1,20 @@ +/* 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; + +public interface LanguageCommentReformatter { + /** Reformats the given comment to match a language comment format */ + String reformat(String comment); +} diff --git a/src/main/java/com/google/api/codegen/util/PassThroughCommentReformatter.java b/src/main/java/com/google/api/codegen/util/PassThroughCommentReformatter.java index 69ef2957e3..4325626d40 100644 --- a/src/main/java/com/google/api/codegen/util/PassThroughCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/PassThroughCommentReformatter.java @@ -14,7 +14,7 @@ */ package com.google.api.codegen.util; -public class PassThroughCommentReformatter implements CommentReformatter { +public class PassThroughCommentReformatter implements LanguageCommentReformatter { @Override public String reformat(String comment) { return comment; diff --git a/src/main/java/com/google/api/codegen/util/csharp/CSharpCommentReformatter.java b/src/main/java/com/google/api/codegen/util/csharp/CSharpCommentReformatter.java index c67cc02ae8..5225e020f5 100644 --- a/src/main/java/com/google/api/codegen/util/csharp/CSharpCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/csharp/CSharpCommentReformatter.java @@ -15,11 +15,11 @@ package com.google.api.codegen.util.csharp; -import com.google.api.codegen.util.CommentReformatter; +import com.google.api.codegen.util.LanguageCommentReformatter; import com.google.common.escape.Escaper; import com.google.common.escape.Escapers; -public class CSharpCommentReformatter implements CommentReformatter { +public class CSharpCommentReformatter implements LanguageCommentReformatter { private static final Escaper CSHARP_ESCAPER = Escapers.builder() diff --git a/src/main/java/com/google/api/codegen/util/java/JavaCommentReformatter.java b/src/main/java/com/google/api/codegen/util/java/JavaCommentReformatter.java index 6e6d03342a..e8cc7d5906 100644 --- a/src/main/java/com/google/api/codegen/util/java/JavaCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/java/JavaCommentReformatter.java @@ -14,11 +14,11 @@ */ package com.google.api.codegen.util.java; -import com.google.api.codegen.util.CommentReformatter; +import com.google.api.codegen.util.LanguageCommentReformatter; import com.google.common.escape.Escaper; import com.google.common.escape.Escapers; -public class JavaCommentReformatter implements CommentReformatter { +public class JavaCommentReformatter implements LanguageCommentReformatter { /** Escaper for formatting javadoc strings. */ private static final Escaper JAVADOC_ESCAPER = Escapers.builder() diff --git a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java index 24ee862790..a580ccb802 100644 --- a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java @@ -16,14 +16,14 @@ import com.google.api.codegen.CommentPatterns; import com.google.api.codegen.util.CommentReformatter; -import com.google.api.codegen.util.CommentReformatting; +import com.google.api.codegen.util.LanguageCommentReformatter; 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 { +public class JSCommentReformatter implements LanguageCommentReformatter { private static Function PROTO_TO_JS_DOC = new Function() { @@ -35,7 +35,7 @@ public String apply(Matcher matcher) { @Override public String reformat(String comment) { - return CommentReformatting.of(comment) + return CommentReformatter.of(comment) .reformat(CommentPatterns.PROTO_LINK_PATTERN, PROTO_TO_JS_DOC) .reformatCloudMarkdownLinks("[%s](%s)") .toString() diff --git a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java index 81943fea66..95a1d29fce 100644 --- a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java @@ -15,19 +15,20 @@ 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; +import com.google.api.codegen.util.LanguageCommentReformatter; +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 class PhpCommentReformatter implements LanguageCommentReformatter { + public static final Pattern ASTERISK_PATTERN = Pattern.compile("\\*"); + public static final Pattern AMPERSAND_PATTERN = Pattern.compile("@"); @Override public String reformat(String comment) { - comment = PHP_ESCAPER.escape(comment); - comment = CommentReformatting.reformatCloudMarkdownLinks(comment, "[%s](%s)"); - return comment.trim(); + return CommentReformatter.of(comment) + .replace(ASTERISK_PATTERN, "*") + .replace(AMPERSAND_PATTERN, "@") + .reformatCloudMarkdownLinks("[%s](%s)") + .toString() + .trim(); } } diff --git a/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java b/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java index c89757cc79..1216f52baf 100644 --- a/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java @@ -16,10 +16,16 @@ import com.google.api.codegen.CommentPatterns; import com.google.api.codegen.util.CommentReformatter; +import com.google.api.codegen.util.LanguageCommentReformatter; +import com.google.common.base.Function; import com.google.common.base.Splitter; import java.util.regex.Matcher; -public class PythonCommentReformatter implements CommentReformatter { +public class PythonCommentReformatter implements LanguageCommentReformatter { + + private static Function PROTO_REPLACE_FUNCTION = + CommentReformatter.reformatLinkFunction("``%s``", ""); + @Override public String reformat(String comment) { boolean inCodeBlock = false; @@ -53,58 +59,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 `_", m.group(1), m.group(2)))); - } while (m.find()); - m.appendTail(sb); - return sb.toString(); + return CommentReformatter.of(line) + .replace(CommentPatterns.BACK_QUOTE_PATTERN, "``") + .reformat(CommentPatterns.PROTO_LINK_PATTERN, PROTO_REPLACE_FUNCTION) + .reformatAbsoluteMarkdownLinks("`%s <%s>`_") + .reformatCloudMarkdownLinks("`%s <%s>`_") + .toString(); } } diff --git a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java index 04f471554b..c9f897b843 100644 --- a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java @@ -16,13 +16,13 @@ import com.google.api.codegen.CommentPatterns; import com.google.api.codegen.util.CommentReformatter; -import com.google.api.codegen.util.CommentReformatting; +import com.google.api.codegen.util.LanguageCommentReformatter; 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 { +public class RubyCommentReformatter implements LanguageCommentReformatter { private static final String BULLET = "* "; private static Function PROTO_TO_RUBY_DOC = @@ -72,8 +72,8 @@ public String reformat(String comment) { } private String applyTransformations(String line) { - line = CommentPatterns.BACK_QUOTE_PATTERN.matcher(line).replaceAll("+"); - return CommentReformatting.of(line) + return CommentReformatter.of(line) + .replace(CommentPatterns.BACK_QUOTE_PATTERN, "+") .reformat(CommentPatterns.PROTO_LINK_PATTERN, PROTO_TO_RUBY_DOC) .reformatCloudMarkdownLinks("{%s}[%s]") .reformatAbsoluteMarkdownLinks("{%s}[%s]") From 8e3d52de6c989e0b63e8e2385acda8cf6e89497f Mon Sep 17 00:00:00 2001 From: Michael Bausor Date: Thu, 18 May 2017 09:30:27 -0700 Subject: [PATCH 06/12] Restructure to CommentTransformer --- .../api/codegen/util/CommentReformatter.java | 92 ------------------- .../api/codegen/util/CommentTransformer.java | 81 ++++++++++++++++ .../api/codegen/util/ProtoLinkPattern.java | 55 +++++++++++ .../codegen/util/js/JSCommentReformatter.java | 19 +--- .../util/php/PhpCommentReformatter.java | 6 +- .../util/py/PythonCommentReformatter.java | 15 +-- .../util/ruby/RubyCommentReformatter.java | 46 ++++++---- 7 files changed, 174 insertions(+), 140 deletions(-) delete mode 100644 src/main/java/com/google/api/codegen/util/CommentReformatter.java create mode 100644 src/main/java/com/google/api/codegen/util/CommentTransformer.java create mode 100644 src/main/java/com/google/api/codegen/util/ProtoLinkPattern.java diff --git a/src/main/java/com/google/api/codegen/util/CommentReformatter.java b/src/main/java/com/google/api/codegen/util/CommentReformatter.java deleted file mode 100644 index 759b7c182a..0000000000 --- a/src/main/java/com/google/api/codegen/util/CommentReformatter.java +++ /dev/null @@ -1,92 +0,0 @@ -/* 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; - -public class CommentReformatter { - - public static String CLOUD_URL_PREFIX = "https://cloud.google.com"; - - private String comment; - - private CommentReformatter(String comment) { - this.comment = comment; - } - - public static CommentReformatter of(String comment) { - return new CommentReformatter(comment); - } - - public CommentReformatter reformat( - Pattern pattern, Function replacementFunction) { - comment = reformatPattern(comment, pattern, replacementFunction); - return this; - } - - public CommentReformatter replace(Pattern pattern, String replacement) { - comment = pattern.matcher(comment).replaceAll(replacement); - return this; - } - - public CommentReformatter reformatAbsoluteMarkdownLinks(String linkFormat) { - comment = - reformatPattern( - comment, CommentPatterns.ABSOLUTE_LINK_PATTERN, reformatLinkFunction(linkFormat, "")); - return this; - } - - public CommentReformatter reformatCloudMarkdownLinks(String linkFormat) { - comment = - reformatPattern( - comment, - CommentPatterns.CLOUD_LINK_PATTERN, - reformatLinkFunction(linkFormat, CLOUD_URL_PREFIX)); - return this; - } - - @Override - public String toString() { - return comment; - } - - public static Function reformatLinkFunction( - final String linkFormat, final String urlPrefix) { - return new Function() { - @Override - public String apply(Matcher matcher) { - String url = urlPrefix + matcher.group(2); - return Matcher.quoteReplacement(String.format(linkFormat, matcher.group(1), url)); - } - }; - } - - private static String reformatPattern( - String comment, Pattern pattern, Function 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(); - } -} diff --git a/src/main/java/com/google/api/codegen/util/CommentTransformer.java b/src/main/java/com/google/api/codegen/util/CommentTransformer.java new file mode 100644 index 0000000000..a608c2604b --- /dev/null +++ b/src/main/java/com/google/api/codegen/util/CommentTransformer.java @@ -0,0 +1,81 @@ +/* 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 transformProtoMarkdownLinks(String linkFormat) { + return transform(ProtoLinkPattern.PROTO.createTransformation(linkFormat, "")); + } + + public CommentTransformer transformAbsoluteMarkdownLinks(String linkFormat) { + return transform(ProtoLinkPattern.ABSOLUTE.createTransformation(linkFormat, "")); + } + + public CommentTransformer transformCloudMarkdownLinks(String linkFormat) { + return transform(ProtoLinkPattern.CLOUD.createTransformation(linkFormat, CLOUD_URL_PREFIX)); + } + + 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 replacementFunction; + + public Transformation(Pattern pattern, Function 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(); + } + } +} diff --git a/src/main/java/com/google/api/codegen/util/ProtoLinkPattern.java b/src/main/java/com/google/api/codegen/util/ProtoLinkPattern.java new file mode 100644 index 0000000000..d8faab9c4f --- /dev/null +++ b/src/main/java/com/google/api/codegen/util/ProtoLinkPattern.java @@ -0,0 +1,55 @@ +/* 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), + PROTO(CommentPatterns.PROTO_LINK_PATTERN); + + private Pattern pattern; + + ProtoLinkPattern(Pattern pattern) { + this.pattern = pattern; + } + + public Pattern getPattern() { + return pattern; + } + + public Transformation createTransformation(final String linkFormat, final String urlPrefix) { + return new Transformation( + getPattern(), + new Function() { + @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)); + } + }); + } +} diff --git a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java index a580ccb802..ed80620ee8 100644 --- a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java @@ -14,30 +14,19 @@ */ 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.LanguageCommentReformatter; 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 LanguageCommentReformatter { - private static Function PROTO_TO_JS_DOC = - new Function() { - @Override - public String apply(Matcher matcher) { - return Matcher.quoteReplacement(String.format("{@link %s}", matcher.group(1))); - } - }; - @Override public String reformat(String comment) { - return CommentReformatter.of(comment) - .reformat(CommentPatterns.PROTO_LINK_PATTERN, PROTO_TO_JS_DOC) - .reformatCloudMarkdownLinks("[%s](%s)") + return CommentTransformer.of(comment) + .transformProtoMarkdownLinks("{@link %s}") + .transformCloudMarkdownLinks("[%s](%s)") .toString() .trim(); } diff --git a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java index 95a1d29fce..6325b42ed9 100644 --- a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java @@ -14,7 +14,7 @@ */ package com.google.api.codegen.util.php; -import com.google.api.codegen.util.CommentReformatter; +import com.google.api.codegen.util.CommentTransformer; import com.google.api.codegen.util.LanguageCommentReformatter; import java.util.regex.Pattern; @@ -24,10 +24,10 @@ public class PhpCommentReformatter implements LanguageCommentReformatter { @Override public String reformat(String comment) { - return CommentReformatter.of(comment) + return CommentTransformer.of(comment) .replace(ASTERISK_PATTERN, "*") .replace(AMPERSAND_PATTERN, "@") - .reformatCloudMarkdownLinks("[%s](%s)") + .transformCloudMarkdownLinks("[%s](%s)") .toString() .trim(); } diff --git a/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java b/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java index 1216f52baf..377c429e41 100644 --- a/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java @@ -15,17 +15,12 @@ package com.google.api.codegen.util.py; 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.LanguageCommentReformatter; -import com.google.common.base.Function; import com.google.common.base.Splitter; -import java.util.regex.Matcher; public class PythonCommentReformatter implements LanguageCommentReformatter { - private static Function PROTO_REPLACE_FUNCTION = - CommentReformatter.reformatLinkFunction("``%s``", ""); - @Override public String reformat(String comment) { boolean inCodeBlock = false; @@ -59,11 +54,11 @@ public String reformat(String comment) { } private String applyTransformations(String line) { - return CommentReformatter.of(line) + return CommentTransformer.of(line) .replace(CommentPatterns.BACK_QUOTE_PATTERN, "``") - .reformat(CommentPatterns.PROTO_LINK_PATTERN, PROTO_REPLACE_FUNCTION) - .reformatAbsoluteMarkdownLinks("`%s <%s>`_") - .reformatCloudMarkdownLinks("`%s <%s>`_") + .transformProtoMarkdownLinks("``%s``") + .transformAbsoluteMarkdownLinks("`%s <%s>`_") + .transformCloudMarkdownLinks("`%s <%s>`_") .toString(); } } diff --git a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java index c9f897b843..591cdaae29 100644 --- a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java @@ -15,7 +15,8 @@ package com.google.api.codegen.util.ruby; 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.CommentTransformer.Transformation; import com.google.api.codegen.util.LanguageCommentReformatter; import com.google.common.base.Function; import com.google.common.base.Splitter; @@ -25,20 +26,25 @@ public class RubyCommentReformatter implements LanguageCommentReformatter { private static final String BULLET = "* "; - private static Function PROTO_TO_RUBY_DOC = - new Function() { - @Override - public String apply(Matcher matcher) { - return Matcher.quoteReplacement(protoToRubyDoc(matcher.group(1))); - } - }; - private static Function HEADLINE_REPLACE = - new Function() { - @Override - public String apply(Matcher matcher) { - return matcher.group().replace("#", "="); - } - }; + private static Transformation PROTO_TO_RUBY_DOC_TRANSFORMATION = + new Transformation( + CommentPatterns.PROTO_LINK_PATTERN, + new Function() { + @Override + public String apply(Matcher matcher) { + return Matcher.quoteReplacement(protoToRubyDoc(matcher.group(1))); + } + }); + + private static Transformation HEADLINE_TRANSFORMATION = + new Transformation( + CommentPatterns.HEADLINE_PATTERN, + new Function() { + @Override + public String apply(Matcher matcher) { + return matcher.group().replace("#", "="); + } + }); @Override public String reformat(String comment) { @@ -72,12 +78,12 @@ public String reformat(String comment) { } private String applyTransformations(String line) { - return CommentReformatter.of(line) + return CommentTransformer.of(line) .replace(CommentPatterns.BACK_QUOTE_PATTERN, "+") - .reformat(CommentPatterns.PROTO_LINK_PATTERN, PROTO_TO_RUBY_DOC) - .reformatCloudMarkdownLinks("{%s}[%s]") - .reformatAbsoluteMarkdownLinks("{%s}[%s]") - .reformat(CommentPatterns.HEADLINE_PATTERN, HEADLINE_REPLACE) + .transform(PROTO_TO_RUBY_DOC_TRANSFORMATION) + .transformCloudMarkdownLinks("{%s}[%s]") + .transformAbsoluteMarkdownLinks("{%s}[%s]") + .transform(HEADLINE_TRANSFORMATION) .toString(); } From 191bb30e0507dc7185d671be90e8ef28b25fb56e Mon Sep 17 00:00:00 2001 From: Michael Bausor Date: Thu, 18 May 2017 09:38:01 -0700 Subject: [PATCH 07/12] Revert rename of CommentReformatter --- .../com/google/api/codegen/transformer/SurfaceNamer.java | 6 +++--- ...guageCommentReformatter.java => CommentReformatter.java} | 2 +- .../api/codegen/util/PassThroughCommentReformatter.java | 2 +- .../api/codegen/util/csharp/CSharpCommentReformatter.java | 4 ++-- .../api/codegen/util/java/JavaCommentReformatter.java | 4 ++-- .../google/api/codegen/util/js/JSCommentReformatter.java | 4 ++-- .../google/api/codegen/util/php/PhpCommentReformatter.java | 4 ++-- .../api/codegen/util/py/PythonCommentReformatter.java | 4 ++-- .../api/codegen/util/ruby/RubyCommentReformatter.java | 4 ++-- 9 files changed, 17 insertions(+), 17 deletions(-) rename src/main/java/com/google/api/codegen/util/{LanguageCommentReformatter.java => CommentReformatter.java} (94%) diff --git a/src/main/java/com/google/api/codegen/transformer/SurfaceNamer.java b/src/main/java/com/google/api/codegen/transformer/SurfaceNamer.java index 07ce7304d6..37283252e5 100644 --- a/src/main/java/com/google/api/codegen/transformer/SurfaceNamer.java +++ b/src/main/java/com/google/api/codegen/transformer/SurfaceNamer.java @@ -26,8 +26,8 @@ import com.google.api.codegen.config.ResourceNameType; import com.google.api.codegen.config.SingleResourceNameConfig; import com.google.api.codegen.config.VisibilityConfig; +import com.google.api.codegen.util.CommentReformatter; import com.google.api.codegen.util.CommonRenderingUtil; -import com.google.api.codegen.util.LanguageCommentReformatter; import com.google.api.codegen.util.Name; import com.google.api.codegen.util.NameFormatter; import com.google.api.codegen.util.NameFormatterDelegator; @@ -64,14 +64,14 @@ public class SurfaceNamer extends NameFormatterDelegator { private final ModelTypeFormatter modelTypeFormatter; private final TypeNameConverter typeNameConverter; - private final LanguageCommentReformatter commentReformatter; + private final CommentReformatter commentReformatter; private final String packageName; public SurfaceNamer( NameFormatter languageNamer, ModelTypeFormatter modelTypeFormatter, TypeNameConverter typeNameConverter, - LanguageCommentReformatter commentReformatter, + CommentReformatter commentReformatter, String packageName) { super(languageNamer); this.modelTypeFormatter = modelTypeFormatter; diff --git a/src/main/java/com/google/api/codegen/util/LanguageCommentReformatter.java b/src/main/java/com/google/api/codegen/util/CommentReformatter.java similarity index 94% rename from src/main/java/com/google/api/codegen/util/LanguageCommentReformatter.java rename to src/main/java/com/google/api/codegen/util/CommentReformatter.java index 3e7ed00b3b..4f43a0c9a4 100644 --- a/src/main/java/com/google/api/codegen/util/LanguageCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/CommentReformatter.java @@ -14,7 +14,7 @@ */ package com.google.api.codegen.util; -public interface LanguageCommentReformatter { +public interface CommentReformatter { /** Reformats the given comment to match a language comment format */ String reformat(String comment); } diff --git a/src/main/java/com/google/api/codegen/util/PassThroughCommentReformatter.java b/src/main/java/com/google/api/codegen/util/PassThroughCommentReformatter.java index 4325626d40..69ef2957e3 100644 --- a/src/main/java/com/google/api/codegen/util/PassThroughCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/PassThroughCommentReformatter.java @@ -14,7 +14,7 @@ */ package com.google.api.codegen.util; -public class PassThroughCommentReformatter implements LanguageCommentReformatter { +public class PassThroughCommentReformatter implements CommentReformatter { @Override public String reformat(String comment) { return comment; diff --git a/src/main/java/com/google/api/codegen/util/csharp/CSharpCommentReformatter.java b/src/main/java/com/google/api/codegen/util/csharp/CSharpCommentReformatter.java index 5225e020f5..c67cc02ae8 100644 --- a/src/main/java/com/google/api/codegen/util/csharp/CSharpCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/csharp/CSharpCommentReformatter.java @@ -15,11 +15,11 @@ package com.google.api.codegen.util.csharp; -import com.google.api.codegen.util.LanguageCommentReformatter; +import com.google.api.codegen.util.CommentReformatter; import com.google.common.escape.Escaper; import com.google.common.escape.Escapers; -public class CSharpCommentReformatter implements LanguageCommentReformatter { +public class CSharpCommentReformatter implements CommentReformatter { private static final Escaper CSHARP_ESCAPER = Escapers.builder() diff --git a/src/main/java/com/google/api/codegen/util/java/JavaCommentReformatter.java b/src/main/java/com/google/api/codegen/util/java/JavaCommentReformatter.java index e8cc7d5906..6e6d03342a 100644 --- a/src/main/java/com/google/api/codegen/util/java/JavaCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/java/JavaCommentReformatter.java @@ -14,11 +14,11 @@ */ package com.google.api.codegen.util.java; -import com.google.api.codegen.util.LanguageCommentReformatter; +import com.google.api.codegen.util.CommentReformatter; import com.google.common.escape.Escaper; import com.google.common.escape.Escapers; -public class JavaCommentReformatter implements LanguageCommentReformatter { +public class JavaCommentReformatter implements CommentReformatter { /** Escaper for formatting javadoc strings. */ private static final Escaper JAVADOC_ESCAPER = Escapers.builder() diff --git a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java index ed80620ee8..04c489f944 100644 --- a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java @@ -15,12 +15,12 @@ package com.google.api.codegen.util.js; import com.google.api.codegen.util.CommentTransformer; -import com.google.api.codegen.util.LanguageCommentReformatter; +import com.google.api.codegen.util.CommentReformatter; import com.google.api.tools.framework.model.ProtoElement; import com.google.api.tools.framework.model.ProtoFile; import com.google.common.collect.ImmutableSet; -public class JSCommentReformatter implements LanguageCommentReformatter { +public class JSCommentReformatter implements CommentReformatter { @Override public String reformat(String comment) { diff --git a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java index 6325b42ed9..b70857b736 100644 --- a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java @@ -15,10 +15,10 @@ package com.google.api.codegen.util.php; import com.google.api.codegen.util.CommentTransformer; -import com.google.api.codegen.util.LanguageCommentReformatter; +import com.google.api.codegen.util.CommentReformatter; import java.util.regex.Pattern; -public class PhpCommentReformatter implements LanguageCommentReformatter { +public class PhpCommentReformatter implements CommentReformatter { public static final Pattern ASTERISK_PATTERN = Pattern.compile("\\*"); public static final Pattern AMPERSAND_PATTERN = Pattern.compile("@"); diff --git a/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java b/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java index 377c429e41..e3cfdb3fa7 100644 --- a/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java @@ -16,10 +16,10 @@ import com.google.api.codegen.CommentPatterns; import com.google.api.codegen.util.CommentTransformer; -import com.google.api.codegen.util.LanguageCommentReformatter; +import com.google.api.codegen.util.CommentReformatter; import com.google.common.base.Splitter; -public class PythonCommentReformatter implements LanguageCommentReformatter { +public class PythonCommentReformatter implements CommentReformatter { @Override public String reformat(String comment) { diff --git a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java index 591cdaae29..f266aeaf06 100644 --- a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java @@ -17,13 +17,13 @@ import com.google.api.codegen.CommentPatterns; import com.google.api.codegen.util.CommentTransformer; import com.google.api.codegen.util.CommentTransformer.Transformation; -import com.google.api.codegen.util.LanguageCommentReformatter; +import com.google.api.codegen.util.CommentReformatter; 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 LanguageCommentReformatter { +public class RubyCommentReformatter implements CommentReformatter { private static final String BULLET = "* "; private static Transformation PROTO_TO_RUBY_DOC_TRANSFORMATION = From 78f98018cba65bb95614b566e53d1fff58d70cfb Mon Sep 17 00:00:00 2001 From: Michael Bausor Date: Thu, 18 May 2017 09:57:05 -0700 Subject: [PATCH 08/12] Push functionality into ProtoLinkPattern --- .../api/codegen/util/CommentTransformer.java | 12 ------------ .../api/codegen/util/ProtoLinkPattern.java | 18 ++++++++---------- .../codegen/util/js/JSCommentReformatter.java | 7 ++++--- .../util/php/PhpCommentReformatter.java | 5 +++-- .../util/py/PythonCommentReformatter.java | 9 +++++---- .../util/ruby/RubyCommentReformatter.java | 7 ++++--- 6 files changed, 24 insertions(+), 34 deletions(-) diff --git a/src/main/java/com/google/api/codegen/util/CommentTransformer.java b/src/main/java/com/google/api/codegen/util/CommentTransformer.java index a608c2604b..32413d8878 100644 --- a/src/main/java/com/google/api/codegen/util/CommentTransformer.java +++ b/src/main/java/com/google/api/codegen/util/CommentTransformer.java @@ -37,18 +37,6 @@ public CommentTransformer replace(Pattern pattern, String replacement) { return this; } - public CommentTransformer transformProtoMarkdownLinks(String linkFormat) { - return transform(ProtoLinkPattern.PROTO.createTransformation(linkFormat, "")); - } - - public CommentTransformer transformAbsoluteMarkdownLinks(String linkFormat) { - return transform(ProtoLinkPattern.ABSOLUTE.createTransformation(linkFormat, "")); - } - - public CommentTransformer transformCloudMarkdownLinks(String linkFormat) { - return transform(ProtoLinkPattern.CLOUD.createTransformation(linkFormat, CLOUD_URL_PREFIX)); - } - public CommentTransformer transform(Transformation transformation) { comment = transformation.apply(comment); return this; diff --git a/src/main/java/com/google/api/codegen/util/ProtoLinkPattern.java b/src/main/java/com/google/api/codegen/util/ProtoLinkPattern.java index d8faab9c4f..df1d7927f7 100644 --- a/src/main/java/com/google/api/codegen/util/ProtoLinkPattern.java +++ b/src/main/java/com/google/api/codegen/util/ProtoLinkPattern.java @@ -26,23 +26,21 @@ * title and link url. */ public enum ProtoLinkPattern { - ABSOLUTE(CommentPatterns.ABSOLUTE_LINK_PATTERN), - CLOUD(CommentPatterns.CLOUD_LINK_PATTERN), - PROTO(CommentPatterns.PROTO_LINK_PATTERN); + 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) { + ProtoLinkPattern(Pattern pattern, String urlPrefix) { this.pattern = pattern; + this.urlPrefix = urlPrefix; } - public Pattern getPattern() { - return pattern; - } - - public Transformation createTransformation(final String linkFormat, final String urlPrefix) { + public Transformation createTransformation(final String linkFormat) { return new Transformation( - getPattern(), + pattern, new Function() { @Override public String apply(Matcher matcher) { diff --git a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java index 04c489f944..c178431256 100644 --- a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java @@ -14,8 +14,9 @@ */ package com.google.api.codegen.util.js; -import com.google.api.codegen.util.CommentTransformer; 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; @@ -25,8 +26,8 @@ public class JSCommentReformatter implements CommentReformatter { @Override public String reformat(String comment) { return CommentTransformer.of(comment) - .transformProtoMarkdownLinks("{@link %s}") - .transformCloudMarkdownLinks("[%s](%s)") + .transform(ProtoLinkPattern.PROTO.createTransformation("{@link %s}")) + .transform(ProtoLinkPattern.CLOUD.createTransformation("[%s](%s)")) .toString() .trim(); } diff --git a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java index b70857b736..a789dfa18d 100644 --- a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java @@ -14,8 +14,9 @@ */ package com.google.api.codegen.util.php; -import com.google.api.codegen.util.CommentTransformer; import com.google.api.codegen.util.CommentReformatter; +import com.google.api.codegen.util.CommentTransformer; +import com.google.api.codegen.util.ProtoLinkPattern; import java.util.regex.Pattern; public class PhpCommentReformatter implements CommentReformatter { @@ -27,7 +28,7 @@ public String reformat(String comment) { return CommentTransformer.of(comment) .replace(ASTERISK_PATTERN, "*") .replace(AMPERSAND_PATTERN, "@") - .transformCloudMarkdownLinks("[%s](%s)") + .transform(ProtoLinkPattern.CLOUD.createTransformation("[%s](%s)")) .toString() .trim(); } diff --git a/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java b/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java index e3cfdb3fa7..f0f30eba8d 100644 --- a/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java @@ -15,8 +15,9 @@ package com.google.api.codegen.util.py; import com.google.api.codegen.CommentPatterns; -import com.google.api.codegen.util.CommentTransformer; 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; public class PythonCommentReformatter implements CommentReformatter { @@ -56,9 +57,9 @@ public String reformat(String comment) { private String applyTransformations(String line) { return CommentTransformer.of(line) .replace(CommentPatterns.BACK_QUOTE_PATTERN, "``") - .transformProtoMarkdownLinks("``%s``") - .transformAbsoluteMarkdownLinks("`%s <%s>`_") - .transformCloudMarkdownLinks("`%s <%s>`_") + .transform(ProtoLinkPattern.PROTO.createTransformation("``%s``")) + .transform(ProtoLinkPattern.ABSOLUTE.createTransformation("`%s <%s>`_")) + .transform(ProtoLinkPattern.CLOUD.createTransformation("`%s <%s>`_")) .toString(); } } diff --git a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java index f266aeaf06..268bff03ac 100644 --- a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java @@ -15,9 +15,10 @@ package com.google.api.codegen.util.ruby; 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.CommentTransformer.Transformation; -import com.google.api.codegen.util.CommentReformatter; +import com.google.api.codegen.util.ProtoLinkPattern; import com.google.common.base.Function; import com.google.common.base.Splitter; import com.google.common.base.Strings; @@ -81,8 +82,8 @@ private String applyTransformations(String line) { return CommentTransformer.of(line) .replace(CommentPatterns.BACK_QUOTE_PATTERN, "+") .transform(PROTO_TO_RUBY_DOC_TRANSFORMATION) - .transformCloudMarkdownLinks("{%s}[%s]") - .transformAbsoluteMarkdownLinks("{%s}[%s]") + .transform(ProtoLinkPattern.CLOUD.createTransformation("{%s}[%s]")) + .transform(ProtoLinkPattern.ABSOLUTE.createTransformation("{%s}[%s]")) .transform(HEADLINE_TRANSFORMATION) .toString(); } From 726a2bf4a4a778262c8c274d3a417f57b1e541ea Mon Sep 17 00:00:00 2001 From: Michael Bausor Date: Fri, 26 May 2017 11:05:41 -0700 Subject: [PATCH 09/12] Remove use of matcher in function signatures --- .../api/codegen/util/CommentTransformer.java | 19 ++++++++++++++++--- .../api/codegen/util/ProtoLinkPattern.java | 6 ++++-- .../util/ruby/RubyCommentReformatter.java | 18 +++++------------- 3 files changed, 25 insertions(+), 18 deletions(-) diff --git a/src/main/java/com/google/api/codegen/util/CommentTransformer.java b/src/main/java/com/google/api/codegen/util/CommentTransformer.java index 32413d8878..9c55f9dc37 100644 --- a/src/main/java/com/google/api/codegen/util/CommentTransformer.java +++ b/src/main/java/com/google/api/codegen/util/CommentTransformer.java @@ -37,6 +37,19 @@ public CommentTransformer replace(Pattern pattern, String replacement) { return this; } + public CommentTransformer scopedReplace( + Pattern pattern, final String target, final String replacement) { + return transform( + new Transformation( + pattern, + new Function() { + @Override + public String apply(String matchedString) { + return matchedString.replace(target, replacement); + } + })); + } + public CommentTransformer transform(Transformation transformation) { comment = transformation.apply(comment); return this; @@ -49,9 +62,9 @@ public String toString() { public static class Transformation { private Pattern pattern; - private Function replacementFunction; + private Function replacementFunction; - public Transformation(Pattern pattern, Function replacementFunction) { + public Transformation(Pattern pattern, Function replacementFunction) { this.pattern = pattern; this.replacementFunction = replacementFunction; } @@ -60,7 +73,7 @@ public String apply(String comment) { StringBuffer sb = new StringBuffer(); Matcher m = pattern.matcher(comment); while (m.find()) { - m.appendReplacement(sb, replacementFunction.apply(m)); + m.appendReplacement(sb, replacementFunction.apply(m.group())); } m.appendTail(sb); return sb.toString(); diff --git a/src/main/java/com/google/api/codegen/util/ProtoLinkPattern.java b/src/main/java/com/google/api/codegen/util/ProtoLinkPattern.java index df1d7927f7..a4a728fa7e 100644 --- a/src/main/java/com/google/api/codegen/util/ProtoLinkPattern.java +++ b/src/main/java/com/google/api/codegen/util/ProtoLinkPattern.java @@ -41,9 +41,11 @@ public enum ProtoLinkPattern { public Transformation createTransformation(final String linkFormat) { return new Transformation( pattern, - new Function() { + new Function() { @Override - public String apply(Matcher matcher) { + public String apply(String matchedString) { + Matcher matcher = pattern.matcher(matchedString); + matcher.find(); String title = matcher.group(1); String url = urlPrefix + matcher.group(2); return Matcher.quoteReplacement(String.format(linkFormat, title, url)); diff --git a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java index 268bff03ac..08f00e8d7f 100644 --- a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java @@ -30,23 +30,15 @@ public class RubyCommentReformatter implements CommentReformatter { private static Transformation PROTO_TO_RUBY_DOC_TRANSFORMATION = new Transformation( CommentPatterns.PROTO_LINK_PATTERN, - new Function() { + new Function() { @Override - public String apply(Matcher matcher) { + public String apply(String matchedString) { + Matcher matcher = CommentPatterns.PROTO_LINK_PATTERN.matcher(matchedString); + matcher.find(); return Matcher.quoteReplacement(protoToRubyDoc(matcher.group(1))); } }); - private static Transformation HEADLINE_TRANSFORMATION = - new Transformation( - CommentPatterns.HEADLINE_PATTERN, - new Function() { - @Override - public String apply(Matcher matcher) { - return matcher.group().replace("#", "="); - } - }); - @Override public String reformat(String comment) { StringBuffer sb = new StringBuffer(); @@ -84,7 +76,7 @@ private String applyTransformations(String line) { .transform(PROTO_TO_RUBY_DOC_TRANSFORMATION) .transform(ProtoLinkPattern.CLOUD.createTransformation("{%s}[%s]")) .transform(ProtoLinkPattern.ABSOLUTE.createTransformation("{%s}[%s]")) - .transform(HEADLINE_TRANSFORMATION) + .scopedReplace(CommentPatterns.HEADLINE_PATTERN, "#", "=") .toString(); } From 06bceaf768efb25a73781c48b39f61dde9660519 Mon Sep 17 00:00:00 2001 From: Michael Bausor Date: Fri, 26 May 2017 12:02:55 -0700 Subject: [PATCH 10/12] Change model to constructed transformer --- .../api/codegen/util/CommentTransformer.java | 75 ++++++++++++------- .../codegen/util/js/JSCommentReformatter.java | 12 +-- .../util/php/PhpCommentReformatter.java | 14 ++-- .../util/py/PythonCommentReformatter.java | 21 +++--- .../util/ruby/RubyCommentReformatter.java | 21 +++--- 5 files changed, 83 insertions(+), 60 deletions(-) diff --git a/src/main/java/com/google/api/codegen/util/CommentTransformer.java b/src/main/java/com/google/api/codegen/util/CommentTransformer.java index 9c55f9dc37..db4c594b43 100644 --- a/src/main/java/com/google/api/codegen/util/CommentTransformer.java +++ b/src/main/java/com/google/api/codegen/util/CommentTransformer.java @@ -15,6 +15,7 @@ package com.google.api.codegen.util; import com.google.common.base.Function; +import com.google.common.collect.ImmutableList; import java.util.regex.Matcher; import java.util.regex.Pattern; @@ -22,42 +23,62 @@ public class CommentTransformer { public static String CLOUD_URL_PREFIX = "https://cloud.google.com"; - private String comment; + private ImmutableList transformations; - private CommentTransformer(String comment) { - this.comment = comment; + private CommentTransformer(ImmutableList transformations) { + this.transformations = transformations; } - public static CommentTransformer of(String comment) { - return new CommentTransformer(comment); + public String transform(String comment) { + for (Transformation transformation : transformations) { + comment = transformation.apply(comment); + } + return comment; } - public CommentTransformer replace(Pattern pattern, String replacement) { - comment = pattern.matcher(comment).replaceAll(replacement); - return this; + public static Builder newBuilder() { + return new Builder(); } - public CommentTransformer scopedReplace( - Pattern pattern, final String target, final String replacement) { - return transform( - new Transformation( - pattern, - new Function() { - @Override - public String apply(String matchedString) { - return matchedString.replace(target, replacement); - } - })); - } + public static class Builder { - public CommentTransformer transform(Transformation transformation) { - comment = transformation.apply(comment); - return this; - } + private ImmutableList.Builder transformations = ImmutableList.builder(); - @Override - public String toString() { - return comment; + private Builder() {} + + public Builder replace(Pattern pattern, final String replacement) { + transformations.add( + new Transformation( + pattern, + new Function() { + @Override + public String apply(String s) { + return replacement; + } + })); + return this; + } + + public Builder scopedReplace(Pattern pattern, final String target, final String replacement) { + return transform( + new Transformation( + pattern, + new Function() { + @Override + public String apply(String matchedString) { + return matchedString.replace(target, replacement); + } + })); + } + + public Builder transform(Transformation transformation) { + transformations.add(transformation); + return this; + } + + public CommentTransformer build() { + return new CommentTransformer(transformations.build()); + } } public static class Transformation { diff --git a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java index c178431256..7f0851def2 100644 --- a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java @@ -23,13 +23,15 @@ public class JSCommentReformatter implements CommentReformatter { + private CommentTransformer transformer = + CommentTransformer.newBuilder() + .transform(ProtoLinkPattern.PROTO.createTransformation("{@link %s}")) + .transform(ProtoLinkPattern.CLOUD.createTransformation("[%s](%s)")) + .build(); + @Override public String reformat(String comment) { - return CommentTransformer.of(comment) - .transform(ProtoLinkPattern.PROTO.createTransformation("{@link %s}")) - .transform(ProtoLinkPattern.CLOUD.createTransformation("[%s](%s)")) - .toString() - .trim(); + return transformer.transform(comment).trim(); } public String getLinkedElementName(ProtoElement element) { diff --git a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java index a789dfa18d..0b9c92b9b3 100644 --- a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java @@ -23,13 +23,15 @@ public class PhpCommentReformatter implements CommentReformatter { public static final Pattern ASTERISK_PATTERN = Pattern.compile("\\*"); public static final Pattern AMPERSAND_PATTERN = Pattern.compile("@"); + private CommentTransformer transformer = + CommentTransformer.newBuilder() + .replace(ASTERISK_PATTERN, "*") + .replace(AMPERSAND_PATTERN, "@") + .transform(ProtoLinkPattern.CLOUD.createTransformation("[%s](%s)")) + .build(); + @Override public String reformat(String comment) { - return CommentTransformer.of(comment) - .replace(ASTERISK_PATTERN, "*") - .replace(AMPERSAND_PATTERN, "@") - .transform(ProtoLinkPattern.CLOUD.createTransformation("[%s](%s)")) - .toString() - .trim(); + return transformer.transform(comment).trim(); } } diff --git a/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java b/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java index f0f30eba8d..0d625b42ea 100644 --- a/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java @@ -22,6 +22,14 @@ public class PythonCommentReformatter implements CommentReformatter { + private CommentTransformer transformer = + CommentTransformer.newBuilder() + .replace(CommentPatterns.BACK_QUOTE_PATTERN, "``") + .transform(ProtoLinkPattern.PROTO.createTransformation("``%s``")) + .transform(ProtoLinkPattern.ABSOLUTE.createTransformation("`%s <%s>`_")) + .transform(ProtoLinkPattern.CLOUD.createTransformation("`%s <%s>`_")) + .build(); + @Override public String reformat(String comment) { boolean inCodeBlock = false; @@ -34,7 +42,7 @@ public String reformat(String comment) { if (!(line.trim().isEmpty() || CommentPatterns.CODE_BLOCK_PATTERN.matcher(line).matches())) { inCodeBlock = false; - line = applyTransformations(line); + line = transformer.transform(line); } } else if (CommentPatterns.CODE_BLOCK_PATTERN.matcher(line).matches()) { @@ -42,7 +50,7 @@ public String reformat(String comment) { line = "::\n\n" + line; } else { - line = applyTransformations(line); + line = transformer.transform(line); } if (!first) { @@ -53,13 +61,4 @@ public String reformat(String comment) { } return sb.toString().trim(); } - - private String applyTransformations(String line) { - 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(); - } } diff --git a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java index 08f00e8d7f..d540e6fb27 100644 --- a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java @@ -39,6 +39,15 @@ public String apply(String matchedString) { } }); + private CommentTransformer transformer = + CommentTransformer.newBuilder() + .replace(CommentPatterns.BACK_QUOTE_PATTERN, "+") + .transform(PROTO_TO_RUBY_DOC_TRANSFORMATION) + .transform(ProtoLinkPattern.CLOUD.createTransformation("{%s}[%s]")) + .transform(ProtoLinkPattern.ABSOLUTE.createTransformation("{%s}[%s]")) + .scopedReplace(CommentPatterns.HEADLINE_PATTERN, "#", "=") + .build(); + @Override public String reformat(String comment) { StringBuffer sb = new StringBuffer(); @@ -63,23 +72,13 @@ public String reformat(String comment) { line = line.trim(); sb.append(Strings.repeat(" ", listIndent)); } - sb.append(applyTransformations(line)).append("\n"); + sb.append(transformer.transform(line)).append("\n"); followsListItem = matchesList; followsBlankLine = line.isEmpty(); } return sb.toString().trim(); } - private String applyTransformations(String line) { - return CommentTransformer.of(line) - .replace(CommentPatterns.BACK_QUOTE_PATTERN, "+") - .transform(PROTO_TO_RUBY_DOC_TRANSFORMATION) - .transform(ProtoLinkPattern.CLOUD.createTransformation("{%s}[%s]")) - .transform(ProtoLinkPattern.ABSOLUTE.createTransformation("{%s}[%s]")) - .scopedReplace(CommentPatterns.HEADLINE_PATTERN, "#", "=") - .toString(); - } - private static String protoToRubyDoc(String comment) { boolean messageFound = false; boolean isFirstSegment = true; From 0ca0060b7521e4a5560cda33c074860a68305fcc Mon Sep 17 00:00:00 2001 From: Michael Bausor Date: Fri, 26 May 2017 12:46:22 -0700 Subject: [PATCH 11/12] Update handling of link formats --- .../google/api/codegen/CommentPatterns.java | 2 +- ...ProtoLinkPattern.java => LinkPattern.java} | 20 ++++++++++++------- .../codegen/util/js/JSCommentReformatter.java | 9 ++++++--- .../util/php/PhpCommentReformatter.java | 7 +++++-- .../util/py/PythonCommentReformatter.java | 11 ++++++---- .../util/ruby/RubyCommentReformatter.java | 9 ++++++--- 6 files changed, 38 insertions(+), 20 deletions(-) rename src/main/java/com/google/api/codegen/util/{ProtoLinkPattern.java => LinkPattern.java} (67%) diff --git a/src/main/java/com/google/api/codegen/CommentPatterns.java b/src/main/java/com/google/api/codegen/CommentPatterns.java index f3bb770b2e..21a4cef26b 100644 --- a/src/main/java/com/google/api/codegen/CommentPatterns.java +++ b/src/main/java/com/google/api/codegen/CommentPatterns.java @@ -24,7 +24,7 @@ public final class CommentPatterns { public static final Pattern BACK_QUOTE_PATTERN = Pattern.compile("(?() { @@ -48,7 +54,7 @@ public String apply(String matchedString) { matcher.find(); String title = matcher.group(1); String url = urlPrefix + matcher.group(2); - return Matcher.quoteReplacement(String.format(linkFormat, title, url)); + return Matcher.quoteReplacement(String.format(finalLinkFormat, title, url)); } }); } diff --git a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java index 7f0851def2..f1c0c99b08 100644 --- a/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/js/JSCommentReformatter.java @@ -16,7 +16,7 @@ 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.codegen.util.LinkPattern; import com.google.api.tools.framework.model.ProtoElement; import com.google.api.tools.framework.model.ProtoFile; import com.google.common.collect.ImmutableSet; @@ -25,8 +25,11 @@ public class JSCommentReformatter implements CommentReformatter { private CommentTransformer transformer = CommentTransformer.newBuilder() - .transform(ProtoLinkPattern.PROTO.createTransformation("{@link %s}")) - .transform(ProtoLinkPattern.CLOUD.createTransformation("[%s](%s)")) + .transform(LinkPattern.PROTO.toFormat("{@link $TITLE}")) + .transform( + LinkPattern.RELATIVE + .withUrlPrefix(CommentTransformer.CLOUD_URL_PREFIX) + .toFormat("[$TITLE]($URL)")) .build(); @Override diff --git a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java index 0b9c92b9b3..8874642f13 100644 --- a/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/php/PhpCommentReformatter.java @@ -16,7 +16,7 @@ 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.codegen.util.LinkPattern; import java.util.regex.Pattern; public class PhpCommentReformatter implements CommentReformatter { @@ -27,7 +27,10 @@ public class PhpCommentReformatter implements CommentReformatter { CommentTransformer.newBuilder() .replace(ASTERISK_PATTERN, "*") .replace(AMPERSAND_PATTERN, "@") - .transform(ProtoLinkPattern.CLOUD.createTransformation("[%s](%s)")) + .transform( + LinkPattern.RELATIVE + .withUrlPrefix(CommentTransformer.CLOUD_URL_PREFIX) + .toFormat("[$TITLE]($URL)")) .build(); @Override diff --git a/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java b/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java index 0d625b42ea..56704e9169 100644 --- a/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/py/PythonCommentReformatter.java @@ -17,7 +17,7 @@ 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.codegen.util.LinkPattern; import com.google.common.base.Splitter; public class PythonCommentReformatter implements CommentReformatter { @@ -25,9 +25,12 @@ public class PythonCommentReformatter implements CommentReformatter { private CommentTransformer transformer = CommentTransformer.newBuilder() .replace(CommentPatterns.BACK_QUOTE_PATTERN, "``") - .transform(ProtoLinkPattern.PROTO.createTransformation("``%s``")) - .transform(ProtoLinkPattern.ABSOLUTE.createTransformation("`%s <%s>`_")) - .transform(ProtoLinkPattern.CLOUD.createTransformation("`%s <%s>`_")) + .transform(LinkPattern.PROTO.toFormat("``$TITLE``")) + .transform(LinkPattern.ABSOLUTE.toFormat("`$TITLE <$URL>`_")) + .transform( + LinkPattern.RELATIVE + .withUrlPrefix(CommentTransformer.CLOUD_URL_PREFIX) + .toFormat("`$TITLE <$URL>`_")) .build(); @Override diff --git a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java index d540e6fb27..167dcb100f 100644 --- a/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java +++ b/src/main/java/com/google/api/codegen/util/ruby/RubyCommentReformatter.java @@ -18,7 +18,7 @@ import com.google.api.codegen.util.CommentReformatter; import com.google.api.codegen.util.CommentTransformer; import com.google.api.codegen.util.CommentTransformer.Transformation; -import com.google.api.codegen.util.ProtoLinkPattern; +import com.google.api.codegen.util.LinkPattern; import com.google.common.base.Function; import com.google.common.base.Splitter; import com.google.common.base.Strings; @@ -43,8 +43,11 @@ public String apply(String matchedString) { CommentTransformer.newBuilder() .replace(CommentPatterns.BACK_QUOTE_PATTERN, "+") .transform(PROTO_TO_RUBY_DOC_TRANSFORMATION) - .transform(ProtoLinkPattern.CLOUD.createTransformation("{%s}[%s]")) - .transform(ProtoLinkPattern.ABSOLUTE.createTransformation("{%s}[%s]")) + .transform( + LinkPattern.RELATIVE + .withUrlPrefix(CommentTransformer.CLOUD_URL_PREFIX) + .toFormat("{$TITLE}[$URL]")) + .transform(LinkPattern.ABSOLUTE.toFormat("{$TITLE}[$URL]")) .scopedReplace(CommentPatterns.HEADLINE_PATTERN, "#", "=") .build(); From 0a4e52cda0f738f85f3bba5ab9b68c32a7b4f152 Mon Sep 17 00:00:00 2001 From: Michael Bausor Date: Fri, 26 May 2017 12:55:57 -0700 Subject: [PATCH 12/12] Update docs --- .../google/api/codegen/util/LinkPattern.java | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/src/main/java/com/google/api/codegen/util/LinkPattern.java b/src/main/java/com/google/api/codegen/util/LinkPattern.java index da6b321666..019e43c499 100644 --- a/src/main/java/com/google/api/codegen/util/LinkPattern.java +++ b/src/main/java/com/google/api/codegen/util/LinkPattern.java @@ -21,9 +21,21 @@ 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. + * An collection of known link patterns found in proto files. The LinkPattern class provides an easy + * way to create Transformation objects for these link patterns into a particular format. + * + *

The format may contain standard Java string format tokens, or the special tokens $TITLE and + * $URL. + * + *

An example creating a Transformation for a relative link would be: + * + * 

+ * 
+ * Transformation transformation = LinkPattern.RELATIVE
+ *    .withUrlPrefix("https://cloud.google.com")
+ *    .toFormat("[$TITLE]($URL)"));
+ * 
+ *
*/ public class LinkPattern { public static LinkPattern ABSOLUTE = new LinkPattern(CommentPatterns.ABSOLUTE_LINK_PATTERN, "");