ruby: YARD documentation warning in google-cloud-compute

[suztomo]

This issue tracks the YARD documentation warnings in google-cloud-compute-v1.

Part of #7452.

Current Situation

When running toys ci --yard --gems google-cloud-compute-v1 (or bundle exec rake yard), YARD documentation generation fails with Yardoc encountered errors due to warnings in proto_docs/google/cloud/compute/v1/compute.rb:

1. Unescaped JSON/Brace Structures (interpreted as broken YARD links):

   • [warn]: In file proto_docs/google/cloud/compute/v1/compute.rb: Cannot resolve link to name: from text: ...
     • Occurs in Google::Cloud::Compute::V1::InstanceGroupManager#all_instances_config and Google::Cloud::Compute::V1::RegionInstanceGroupManager#all_instances_config from literal {name: "app1", ...} in proto docstrings.
   • [warn]: In file proto_docs/google/cloud/compute/v1/compute.rb: Cannot resolve link to min: from text: ...
     • Occurs in Google::Cloud::Compute::V1::InterconnectAttachmentConfigurationConstraints#bgp_peer_asn_ranges and Google::Cloud::Compute::V1::InterconnectRemoteLocationConstraints from multiline {min: ...} structures in proto docstrings.

2. Unknown Tag Warnings:

   • [warn]: Unknown tag @pattern
     • Occurs in Google::Cloud::Compute::V1::InstanceGroupManager#base_instance_name from proto comments containing @pattern: ....
   • [warn]: Unknown tag @required
     • Occurs in Google::Cloud::Compute::V1::InstanceReference#instance from proto comments containing @required: ....

Impact

In google-cloud-compute-v1/Rakefile, YARD is configured by default with --fail-on-warning:

YARD::Rake::YardocTask.new do |y|
  y.options << "--fail-on-warning"
end

Consequently, while toys ci --test --rubocop --doctest passes cleanly, any run including --yard fails.

Resolution

PR submitted: googleapis/gapic-generator-ruby#1337

1. Escapes multi-line braces ((?<!\\)\{(?=[^\s]) -> \{) outside backticks so multiline JSON/range expressions are not parsed as object links.
2. Sanitizes unknown doc tags ((?<=\A|\s)@tag outside backticks -> `@tag`) so proto comments like @pattern or @required are not parsed as unrecognized YARD tags.

How to Confirm a Change in gapic-generator-ruby with Librarian Locally

Librarian executes protoc-gen-ruby_cloud from its Ruby tools cache directory (~/.cache/librarian/bin/ruby_tools). To test local changes made in gapic-generator-ruby against Librarian generation without publishing a new gem release:

1. Build the local gem in gapic-generator-ruby:

   cd /path/to/gapic-generator-ruby/gapic-generator
   gem build gapic-generator.gemspec

2. Install the built gem into Librarian's Ruby tools cache directory:

   gem install gapic-generator-*.gem \
     --install-dir ~/.cache/librarian/bin/ruby_tools \
     --bindir ~/.cache/librarian/bin/ruby_tools/bin \
     --no-document

   (If changes were also made to gapic-generator-cloud, build and install gapic-generator-cloud.gemspec into the same directory.)

3. Run Librarian generation in google-cloud-ruby:

   cd /path/to/google-cloud-ruby
   librarian generate --all
   # Or for a specific gem:
   librarian generate --target google-cloud-compute-v1

4. Verify CI and YARD checks:

   toys ci --yard --gems google-cloud-compute-v1
   toys ci --test --rubocop --doctest --gems google-cloud-compute-v1

[suztomo]

This is not just google-cloud-compute-v1 problem. For example, the "100" item in the multi-line list of the google-apps-chat-v1/latest/Google-Apps-Card-V1-MaterialIcon message definition at https://github.com/googleapis/googleapis/blob/a0cd3979560fe756f652608469ef23a09b3fdb10/google/apps/card/v1/card.proto#L1676

  // The stroke weight of the icon. Choose from {100, 200, 300, 400,
  // 500, 600, 700}. If absent, default value is 400. If any other value is
  // specified, the default value is used.
  //
  // To preview different icon settings, go to
  // [Google Font Icons](https://fonts.google.com/icons) and adjust the
  // settings under **Customize**.
  int32 weight = 3;

has been missing in the reference documentation in Cloud RAD https://docs.cloud.google.com/ruby/docs/reference/google-apps-chat-v1/latest/Google-Apps-Card-V1-MaterialIcon:

The first item in the braces is missing:

and rubydoc.info: https://rubydoc.info/gems/google-apps-chat-v1/Google/Apps/Card/V1/MaterialIcon