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

Offen Anfängerfreundlich
  • Stimmt etwas nicht?
#772 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
2/5
Geschätzter Aufwand
1-3 Stunden
Anfängerfreundlichkeit
78/100
Issue-Typ
Bug
Klarheit
Klar beschrieben
Aktivitätsstatus
Aktiv
Tech-Stack
ruby, sqlite
Bereich
documentation

Rechercherichtung

Lies ext/sqlite3/database.c und lib/sqlite3/database.rb:387, wo der Issue die Methode und den Alias nennt. Prüfe, wie RDoc die C-Methode darstellt, wenn der Ruby-Alias vorhanden ist, wende dann die vorgeschlagene Aliasänderung an und führe bundle exec rdoc aus. Fertig ist die Änderung, wenn der generierte Eintrag für busy_timeout= seine Beschreibung enthält und busy_timeout weiterhin als sein Alias dokumentiert ist.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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.

Vorherrschende Sprache
Ruby
Sterne
845
Forks
224
Ø Merge
2 T. 1 Std.
Gemergte PRs (30 T.)
17

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus sparklemotion/sqlite3-ruby

Alle Issues in sparklemotion/sqlite3-ruby

Ähnliche Issues

Weitere Issues zu Ruby

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.