token_stream and skip_document inconsistency

Aberta
  • Algo errado?
#1,492 1 comentário 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
35/100
Tipo de issue
Bug
Clareza
Razoavelmente clara
Status de atividade
Estagnada
Stack de tecnologia
c, ruby
Domínio
documentation, tooling

Direção de pesquisa

Comece com a reprodução em C fornecida e inspecione como o RDoc associa token_stream a métodos que compartilham uma mesma origem, especialmente o tratamento de skip_description e call-seq. Compare os métodos afetados listados e confirme que o método omitido de call-seq não se torna a definição principal; o trabalho estará concluído quando as descrições e os alternadores de Source estiverem disponíveis de forma consistente para aliases.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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
Linguagem predominante
Ruby
Estrelas
928
Forks
470
Merge médio
2d 4min
PRs com merge (30d)
13

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de ruby/rdoc

Todas as issues de ruby/rdoc

Issues semelhantes

Mais issues de Ruby

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.