token_stream and skip_document inconsistency
Nobody has claimed this yet.
- Dominant language
- Ruby
- Stars
- 930
- Forks
- 465
- Avg merge
- 3d 10h
- Merged PRs (30d)
- 27
Description
Complex#conjugate have token_stream but marked as skip_document
Complex#conjugate has ▶︎Source toggle but description is skipped.
Complex#conj has document but ▶︎Source is not available.
The behavior of this bug looks similar to #1335 but the cause is different.
skip_description
# Whether to skip the method description, true for methods that have
# aliases with a call-seq that doesn't include the method name.
I think this design decision makes sense. There is a room for discussion whether we really need to generate duplicated document for the same method.
token_stream
Among method/aliases with the same source, RDoc seems to select one main method. token_stream is associated to that method object.
RDoc shouldn't select description-skipped method object as main method.
Reproduction code
/*
* call-seq:
* conj -> complex
* Description
*/
VALUE rb_complex_conjugate(VALUE self){return Qnil;}
void Init_Foo(){
rb_cComplex = rb_define_class("Complex", rb_cObject);
rb_define_method(rb_cComplex, "conjugate", rb_complex_conjugate, 0);
rb_define_method(rb_cComplex, "conj", rb_complex_conjugate, 0);
}
RDoc thinks the first define_method (conjugate) is the main definition. token_stream is associated to it. But conjugate is not in call-seq.
Methods that have this problem
Complex#conjugate
Complex#imaginary
Complex#rectangular
Enumerable#collect
Enumerable#find_all
Enumerable#member?
Forwardable#instance_delegate
Hash#initialize_copy
IO#each
Integer#===
MatchData#eql?
Numeric#conjugate
Numeric#imaginary
Numeric#rectangular
ObjectSpace::WeakMap#include?
Range#member?
Regexp#eql?
SingleForwardable#single_delegate
StringIO#each
StringIO#eof
Time#getgm
Time#gmtime
Time#gmtoff
Time#isdst
Time#tv_nsec
Time#tv_usec
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 supplied C reproduction and inspect how RDoc associates token_stream with methods sharing one source, especially the skip_description and call-seq handling. Compare the listed affected methods and confirm that the method omitted from call-seq does not become the main definition; done means descriptions and Source toggles are consistently available for aliases.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c, ruby
- Domain
- documentation, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100