doc: Database#busy_timeout= renders without its description (shadowed by alias_method in database.rb)

Aperta Adatta ai principianti
  • Qualcosa non va?
#772 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
78/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
ruby, sqlite
Ambito
documentation

Direzione di ricerca

Leggi ext/sqlite3/database.c e lib/sqlite3/database.rb:387, dove l’issue identifica il metodo e l’alias. Controlla come RDoc visualizza il metodo C quando è presente l’alias Ruby, quindi applica la modifica suggerita all’alias ed esegui bundle exec rdoc. Il lavoro è completo quando la voce generata per busy_timeout= include la sua descrizione e busy_timeout rimane documentato come suo alias.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Summary

The generated docs show Database#busy_timeout= with no description. Its rdoc comment in ext/sqlite3/database.c ("Indicates that if a request for a resource terminates because that resource is busy, …") is never rendered, on main too, so anything added to that comment is invisible in the published docs. #771 adds text there about holding the GVL and deferring interrupts, which is how this came up.

Cause

lib/sqlite3/database.rb:387:

alias_method :busy_timeout, :busy_timeout=

When RDoc (8.1.0 here) parses this, it creates an undocumented busy_timeout= entry for SQLite3::Database, and that entry takes the place of the C method's documentation.

Checked by running rdoc on subsets of the files:

Files given to rdoc busy_timeout= description rendered
ext/sqlite3/database.c alone yes
ext/sqlite3/database.c + lib/sqlite3/pragmas.rb yes
ext/sqlite3/database.c + lib/sqlite3/database.rb no
the whole repo (bundle exec rdoc, as rdoc.yml runs it) no
ext/sqlite3/database.c + lib/sqlite3/database.rb without the alias_method line yes

Suggested fix

Define the alias in C, next to the method, and drop the Ruby alias_method:

    rb_define_method(cSqlite3Database, "busy_timeout=", set_busy_timeout, 1);
    rb_define_alias(cSqlite3Database, "busy_timeout", "busy_timeout=");

With that change, the busy_timeout= description renders, and busy_timeout still appears as "Alias for: busy_timeout=". Runtime behaviour is unchanged, since both define the same alias on SQLite3::Database.

I haven't included this in #771 to keep that PR focused. Happy to open a separate PR if you'd like.

Lingua principale
Ruby
Stelle
845
Fork
224
Merge medio
2g 1h
PR unite (30g)
17

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di sparklemotion/sqlite3-ruby

Tutte le issue di sparklemotion/sqlite3-ruby

Issue simili

Altre issue su Ruby

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.