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

Ouverte Adaptée aux débutants
  • Quelque chose ne va pas ?
#772 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
2/5
Temps estimé
1-3 heures
Accessibilité débutants
78/100
Type d'issue
Bug
Clarté
Clairement spécifiée
Activité
Active
Stack technique
ruby, sqlite
Domaine
documentation

Piste de recherche

Lis ext/sqlite3/database.c et lib/sqlite3/database.rb:387, où l’issue indique la méthode et l’alias. Vérifie comment RDoc affiche la méthode C lorsque l’alias Ruby est présent, puis applique le changement d’alias suggéré et exécute bundle exec rdoc. Le travail est terminé lorsque l’entrée générée pour busy_timeout= inclut sa description et que busy_timeout reste documenté comme son alias.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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.

Langage dominant
Ruby
Étoiles
845
Forks
224
Merge moyen
2 j 1 h
PR mergées (30 j)
17

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de sparklemotion/sqlite3-ruby

Toutes les issues de sparklemotion/sqlite3-ruby

Issues similaires

Plus d'issues Ruby

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.