Omit descriptions and parameter lists for methods defined in C not mentioned in call-seq #978
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…ntioned in call-seq This allows RDoc to better generate documentation for methods following the Ruby core documentation guide (which omits aliases in call-seq in most cases). This makes documentation for methods defined in C more similar to methods defined in Ruby. For methods defined in Ruby, the method description of the aliased method is already not used (you have to explicitly document the alias to use it). Internally, this adds AnyMethod#has_call_seq? and #skip_description?, and updates Darkfish to: * only show the method name if there is a call-seq for the method, but the call-seq omits the method * to omit the method description if the method is an alias or has aliases and has a call-seq that does not include the method See discussion in ruby/ruby#7316 for details.
|
@jeremyevans I appreciate the vote of confidence in requesting my review, but I'm not too familiar with this part of RDoc. You probably have more context then I do, we can ask in slack about getting you commit access if that helps. Happy to pull this down and try it out too if that is helpful! |
|
@zzak That's OK, I just requested review from you as I saw you had recent commits. I already have commit access, so I could merge this myself, but I thought it best to have it reviewed by someone possibly more familiar with the internals. Taking another look at the commit log, maybe I can ask @nobu. |
nobu
approved these changes
Jul 5, 2023
| # aliases with a call-seq that doesn't include the method name. | ||
|
|
||
| def skip_description? | ||
| has_call_seq? && call_seq.nil? && !!(is_alias_for || !aliases.empty?) |
There was a problem hiding this comment.
The condition around aliases with has_call_seq? seems complicated a little.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This allows RDoc to better generate documentation for methods following the Ruby core documentation guide (which omits aliases in call-seq in most cases). This makes documentation for methods defined in C more similar to methods defined in Ruby. For methods defined in Ruby, the method description of the aliased method is already not used (you have to explicitly document the alias to use it).
Internally, this adds AnyMethod#has_call_seq? and #skip_description?, and updates Darkfish to:
See discussion in ruby/ruby#7316 for discussion leading to this pull request.