feat: Escape xrefs for README files

gapic-generator/lib/gapic/formatting_utils.rb

@@ -36,9 +36,10 @@ class << self
       #
       # @param api [Gapic::Schema::Api]
       # @param lines [Enumerable<String>]
-      # @param disable_xrefs [Boolean] (default is `false`) Disable linking to
+      # @param disable_xrefs [Boolean, Nil] (default is `false`) Disable linking to
       #   cross-references, and render them simply as text. This can be used if
       #   it is known that the targets are not present in the current library.
+      #   Providing a Nil value completely escapes xrefs, rendering the original line.
       # @param transport [:grpc,:rest] Whether xref links should go to REST or
       #   gRPC client classes. Uses the default transport if not provided.
       # @return [Enumerable<String>]
@@ -115,7 +116,7 @@ def escape_line_braces line
       def format_line_xrefs api, line, disable_xrefs, transport
         while (m = @xref_detector.match line)
           entity = api.lookup m[:addr]
-          return line if entity.nil?
+          return line if entity.nil? || disable_xrefs.nil?
           text = m[:text]
           yard_link = disable_xrefs ? text : yard_link_for_entity(entity, text, transport)
           return line if yard_link.nil?

gapic-generator/lib/gapic/presenters/gem_presenter.rb

@@ -134,7 +134,7 @@ def gemspec_description
       def readme_description
         has_markdown = description.strip.start_with? "#"
         desc = has_markdown ? description.split("\n") : [description.gsub(/\s+/, " ").strip]
-        Gapic::FormattingUtils.format_doc_lines @api, desc
+        Gapic::FormattingUtils.format_doc_lines @api, desc, disable_xrefs: nil
       end
 
       def summary

gapic-generator/test/gapic/formatting_utils_test.rb

@@ -387,6 +387,26 @@ def test_xref_service
     assert_equal ["Hello, {::Google::Cloud::Example::Earth::Client World}!\n"], result
   end
 
+  def test_disable_xref_for_service
+    api = FakeApi.new do |api|
+      api.add_file! "google.cloud.example" do
+        api.add_service! "Earth"
+      end
+    end
+    result = Gapic::FormattingUtils.format_doc_lines api, ["Hello, [World][google.cloud.example.Earth]!\n"], disable_xrefs: true
+    assert_equal ["Hello, World!\n"], result
+  end
+
+  def test_escape_xref_for_service
+    api = FakeApi.new do |api|
+      api.add_file! "google.cloud.example" do
+        api.add_service! "Earth"
+      end
+    end
+    result = Gapic::FormattingUtils.format_doc_lines api, ["Hello, [World][google.cloud.example.Earth]!\n"], disable_xrefs: nil
+    assert_equal ["Hello, [World][google.cloud.example.Earth]!\n"], result
+  end
+
   def test_xref_service_rest
     api = FakeApi.new do |api|
       api.add_file! "google.cloud.example" do