Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Print warnings for rdoc-ref links that can't be resolved #1241

Merged
merged 1 commit into from
Dec 16, 2024

Conversation

st0012
Copy link
Member

@st0012 st0012 commented Dec 14, 2024

If warn_missing_rdoc_ref in .rdoc_options is specified to true, or if --warn-missing-rdoc-ref flag is used, then RDoc will print messages reminding the user that a rdoc-ref: link could not be resolved.

Some examples:

Net/HTTP.html: `rdoc-ref:Net::HTTP#active?` can't be resolved for `#active?`
Net/HTTP.html: `rdoc-ref:Net::HTTP#get2` can't be resolved for `#get2`
Net/HTTP.html: `rdoc-ref:Net::HTTP#head2` can't be resolved for `#head2`
Net/HTTP.html: `rdoc-ref:Net::HTTP#post2` can't be resolved for `#post2`
Net/HTTP.html: `rdoc-ref:Net::HTTP#proxyaddr` can't be resolved for `#proxyaddr`
Net/HTTP.html: `rdoc-ref:Net::HTTP.is_version_1_2?` can't be resolved for `::is_version_1_2?`

Unfortunately, due to the timing cross-reference happens, we can't get more detailed locations on the links. But I think we can improve it incrementally too.

ruby/ruby#12344 was discovered through this feature. There are around 50+ missing links in ruby/ruby atm.

Next Steps

  1. Use this to address all missing links in ruby/ruby
  2. Turn the flag on in ruby/ruby
  3. Turn the flag on by default
  4. (Maybe) add rdoc --detect-dead-rdoc-ref or something similar so projects can run it on CI

@st0012 st0012 merged commit 4a5206a into master Dec 16, 2024
43 checks passed
@st0012 st0012 deleted the warn-failed-rdoc-ref-links branch December 16, 2024 19:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Development

Successfully merging this pull request may close these issues.

2 participants