token_stream and skip_document inconsistency #1492

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