Add :deprecated: and :since: directives
Nobody has claimed this yet.
- Dominant language
- Ruby
- Stars
- 930
- Forks
- 465
- Avg merge
- 3d 10h
- Merged PRs (30d)
- 27
Description
On ruby-core, a suggestion was made to add version information to all function documentation. I think that making it easier to do in a standardized way would be good. In my comment, I suggested a couple of directives:
:deprecated since::since:
I believe that :deprecated: is a better choice than :deprecated since:.
This isn’t entirely necessary, but it would make adopting this to be generated in a standard place for both web generated code and RI.
This would be used as:
# This function...
# Use #bar instead.
#
# :deprecated: 2.6
def foo(flag)
# ...
end
# This function...
#
# :since: 3.0
def bar(enable: false)
# ...
end
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
Review the proposed :deprecated: and :since: examples and the linked ruby-core suggestion first. Locate how RDoc directives are parsed and rendered for generated web documentation and RI, then define the behavior needed for both outputs and verify that the directives are standardized.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ruby
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100