gapic-generator 0.51.1 → 0.52.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eacc61ce38027f685621213ffaca3db69125b98c6a1d4d377984ee87d3b5d300
-  data.tar.gz: 72ff91b581965488f97e8e521bb38847234d32c3ffb1a3b229e056f33129fa1c
+  metadata.gz: b45efa15311119a19ee117f8eaf8fa2af651151a80f8ed004373b232652f599f
+  data.tar.gz: 69203b61e070ca8a4a02e901299739754f1048aa935025fd9ac53af072a5aac7
 SHA512:
-  metadata.gz: b8509223c3abf3617ef9bd7c6ea6aef239b57f8e60e774a33df471d131106ecb2a1942e6be9a374c2540753fa0d50ad91e2519ed5fa096ef391c946b35129c4f
-  data.tar.gz: ff480bcbf75f4181647600ed686822911628f6cc98c3f048d91ba46af89cb31fb2db6faf7dfc3332dd2e30ce671574e8347d1149cd6cb25c874feb05788bc8af
+  metadata.gz: 10fbd033561469722836fbbb60888097f91571179880221a033aff5e14be7e980c6a5e94e8383305a7422df16d7158ecf39f54a312c742ea642892927d7b248a
+  data.tar.gz: 5718898dd81be9b2b3eedf1dc188f61821f2d2d012daf12a82510ba1b09fd696c4594b6dbedee6c19b31ec64da5f15bca4c0ce4a98749c20e1f80aa64975aa8c

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History for gapic-generator
 
+### 0.52.0 / 2026-09-04
+
+* Fix: escape multi-line braces and backtick unknown doc tags in yard formatting
+* Fix: rejoin split doc URLs (b/153077040) and strip non-existent message links (b/158466893)
+* Feature: add ruby-cloud-renamed-from for renamed wrapper gems
+
 ### 0.51.1 / 2026-08-05
 
 No significant changes

data/lib/gapic/formatting_utils.rb

@@ -21,16 +21,30 @@ module Gapic
   # Various string formatting utils
   #
   module FormattingUtils
-    @brace_detector = /\A(?<pre>[^`]*(?:`[^`]*`[^`]*)*[^`\\])?\{(?<inside>[^\s][^}]*)\}(?<post>.*)\z/m
     @xref_detector = /\A(?<pre>[^`]*(?:`[^`]*`[^`]*)*)?\[(?<text>[\w. `-]+)\]\[(?<addr>[\w.]+)\](?<post>.*)\z/m
     @list_element_detector = /\A\s*(?:\*|\+|-|[0-9a-zA-Z]+\.)\s/
     @omit_lines = ["@InputOnly\n", "@OutputOnly\n"]
+    # Built-in YARD meta-data tags as documented in:
+    # https://rubydoc.info/gems/yard/file/docs/Tags.md#Tag_List
+    @known_yard_tags = [
+      "abstract", "api", "attr", "attr_reader", "attr_writer", "author", "deprecated", "example",
+      "note", "option", "overload", "param", "private", "raise", "return", "see", "since", "todo",
+      "version", "yield", "yieldparam", "yieldreturn"
+    ].freeze
+
+    # Non-existent messages referenced in proto documentation comments (b/158466893).
+    # Cross-references to these messages (or their fields) cannot be resolved, so the links
+    # are stripped to avoid broken documentation references.
+    @non_existent_messages = [
+      "google.cloud.automl.v1.ColumnSpec"
+    ].freeze
 
     class << self
       ##
       # Given an enumerable of lines, performs yardoc formatting, including:
       # * Interpreting cross-references identified as described in AIP 192
       # * Escaping literal braces that look like yardoc type links
+      # * Backticking unknown doc tags so they are not parsed as YARD tags
       #
       # Tries to be smart about exempting preformatted text blocks.
       #
@@ -45,23 +59,26 @@ module Gapic
       #
       def format_doc_lines api, lines, disable_xrefs: false, transport: nil
         transport ||= api&.default_transport || :grpc
-        # To detect preformatted blocks, this tracks the "expected" base indent
-        # according to Markdown. Specifically, this is the effective indent of
-        # previous block, which is normally 0 except if we're in a list item.
-        # Then, if a block is indented at least 4 spaces past that expected
-        # indent (and as long as it remains so), those lines are considered
-        # preformatted.
+        lines = rejoin_split_urls lines
+        in_fence = in_code_span = false
         in_block = nil
         base_indent = 0
         (lines - @omit_lines).map do |line|
-          indent = line_indent line
-          if indent.nil?
+          if line =~ /^\s*(?:```|~~~)/
+            in_fence = !in_fence
+            in_code_span = false
             in_block = nil
-          else
-            in_block, base_indent = update_indent_state in_block, base_indent, line, indent
-            if in_block == false
-              line = escape_line_braces line
-              line = format_line_xrefs api, line, disable_xrefs, transport
+          elsif !in_fence
+            indent = line_indent line
+            if indent.nil?
+              in_block = nil
+              in_code_span = false
+            else
+              in_block, base_indent = update_indent_state in_block, base_indent, line, indent
+              if in_block == false
+                line, in_code_span = format_line_content line, in_code_span
+                line = format_line_xrefs api, line, disable_xrefs, transport
+              end
             end
           end
           line
@@ -88,6 +105,21 @@ module Gapic
 
       private
 
+      def rejoin_split_urls lines
+        return lines if lines.empty?
+
+        # Fix for misformatted markdown links across line breaks (b/153077040).
+        # Callers may pass lines with trailing newlines (e.g., from String#each_line in schema wrappers)
+        # or without trailing newlines (e.g., from String#split("\n") in GemPresenter#readme_description).
+        # We must preserve the presence or absence of trailing newlines on each element.
+        has_newlines = lines.any? { |l| l.end_with? "\n" }
+        if has_newlines
+          lines.join.gsub(%r{https:\n\s*//}, "https://").each_line.to_a
+        else
+          lines.join("\n").gsub(%r{https:\n\s*//}, "https://").split("\n", -1)
+        end
+      end
+
       def update_indent_state in_block, base_indent, line, indent
         if in_block != true && @list_element_detector =~ line
           in_block = false
@@ -106,15 +138,50 @@ module Gapic
         m[1].length
       end
 
-      def escape_line_braces line
-        while (m = @brace_detector.match line)
-          line = "#{m[:pre]}\\\\{#{m[:inside]}}#{m[:post]}"
+      def format_line_content line, in_code_span
+        parts = line.split("`", -1)
+        formatted_parts = parts.each_with_index.map do |part, idx|
+          if in_code_span
+            in_code_span = false if idx < parts.length - 1
+            part
+          else
+            is_followed_by_backtick = idx < parts.length - 1
+            in_code_span = true if is_followed_by_backtick
+            formatted = escape_prose_braces part, is_followed_by_backtick: is_followed_by_backtick
+            sanitize_prose_tags formatted
+          end
+        end
+        [formatted_parts.join("`"), in_code_span]
+      end
+
+      def escape_prose_braces text, is_followed_by_backtick: false
+        # Matches unescaped `{` outside backtick spans followed by non-whitespace.
+        # If `{` is at the end of a non-code chunk (is_followed_by_backtick: true), it is followed
+        # immediately by a backticked code span (starting with a non-whitespace backtick),
+        # so \z (end of string) is also matched.
+        pattern = is_followed_by_backtick ? /(?<!\\)\{(?=[^\s]|\z)/ : /(?<!\\)\{(?=[^\s])/
+        text.gsub(pattern) { "\\\\{" }
+      end
+
+      def sanitize_prose_tags text
+        # Matches doc tags starting with `@` at the start of a line or preceded by whitespace.
+        # Avoids matching `@` within email addresses (e.g. user@example.com) or quotes.
+        # Any tag not in the YARD recognized list (or starting with `!`) is wrapped in backticks
+        # so YARD renders it as literal text rather than an unrecognized tag directive.
+        text.gsub(/(?<=\A|\s)@([a-zA-Z_]\w*)/) do |match|
+          tag = Regexp.last_match 1
+          @known_yard_tags.include?(tag) || tag.start_with?("!") ? match : "`#{match}`"
         end
-        line
       end
 
       def format_line_xrefs api, line, disable_xrefs, transport
         while (m = @xref_detector.match line)
+          # Remove links to known non-existent messages (b/158466893)
+          if @non_existent_messages.any? { |msg| m[:addr] == msg || m[:addr].start_with?("#{msg}.") }
+            line = "#{m[:pre]}#{m[:text]}#{m[:post]}"
+            next
+          end
+
           entity = api.lookup m[:addr]
           is_mixin_field_addr = Gapic::Model::Mixins.mixin_message_field_address?(
             m[:addr],

data/lib/gapic/generator/version.rb

@@ -16,6 +16,6 @@
 
 module Gapic
   module Generator
-    VERSION = "0.51.1"
+    VERSION = "0.52.0"
   end
 end

data/lib/gapic/generators/default_generator_parameters.rb

@@ -40,6 +40,7 @@ module Gapic
         ":gem.:homepage",
         ":gem.:env_prefix",
         ":gem.:version_dependencies",
+        ":gem.:renamed_from",
         ":gem.:migration_version",
         ":gem.:product_documentation_url",
         ":gem.:issue_tracker_url",
@@ -83,6 +84,7 @@ module Gapic
         "gem-homepage"              => ":gem.:homepage",
         "gem-env-prefix"            => ":gem.:env_prefix",
         "gem-wrapper-of"            => ":gem.:version_dependencies",
+        "gem-renamed-from"          => ":gem.:renamed_from",
         "gem-migration-version"     => ":gem.:migration_version",
         "gem-product-url"           => ":gem.:product_documentation_url",
         "gem-issues-url"            => ":gem.:issue_tracker_url",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gapic-generator
 version: !ruby/object:Gem::Version
-  version: 0.51.1
+  version: 0.52.0
 platform: ruby
 authors:
 - Ernest Landrito