open-telemetry / open-telemetry/opentelemetry-ruby

Support YARD's experimental type parser by removing "optional" from type descriptions

Open
#1,553 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

keep
Dominant language
Ruby
Stars
606
Forks
301
Avg merge
3d 19h
Merged PRs (30d)
42

Description

In https://github.com/open-telemetry/opentelemetry-ruby/pull/1517#discussion_r1379707498, @olleolleolle brought to our attention the YARD experimental type parser does not support [optional Type] argument descriptions in the documentation. One suggested alternative approach is to include the word optional in the description of the argument. This pattern is common in the opentelemetry-ruby repo.

Here's one place where the [optional Type] pattern is used:
https://github.com/open-telemetry/opentelemetry-ruby/blob/a9bcbda1ffca0e781e174da7bdaeb1a83394c595/api/lib/opentelemetry/baggage.rb#L27-L29

Let's revisit our pattern for declaring optional types and determine if we want to adopt a change that supports YARD's type parser.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked discussion and the YARD experimental type parser documentation, then inspect the example in api/lib/opentelemetry/baggage.rb at lines 27-29. Search the repository for the [optional Type] pattern and determine the desired replacement; the work is done when the adopted convention supports YARD's parser consistently.

Written by the indexing model from the issue text.

Assessment

Tech stack
ruby
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.