open-telemetry / open-telemetry/opentelemetry-ruby
Support YARD's experimental type parser by removing "optional" from type descriptions
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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