C parser drops docs under namespace variables defined in another file
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
評価
- 難易度
- 4/5
- 見積もり時間
- 3〜5日
- 初心者へのやさしさ
- 55/100
- issue の種類
- バグ
- 明瞭さ
- おおむね明確
- 活発さ
- 静か
- 領域
- documentation, tooling
調査の方向性
C parser による rb_define_const とメソッド定義の処理を追跡し、parser ローカルな @known_classes の検索と、rb_define_class_under および rb_define_module_under が使用する store ベースの enclosure 検索を比較してください。2 ファイルの mFoo の例で動作を検証してください。別のファイルで mFoo の後に定義された定数とメソッドは、偽の seed コメントを必要とせずに Foo の下に現れるはずです。
索引モデルが issue の本文から書いたものです。
説明
C parser drops docs for entries under a namespace variable defined in another file
RDoc's C parser appears unable to resolve extension namespace variables across C files for constants and methods.
Example:
/* foo.c */
VALUE mFoo;
void Init_foo(void) {
mFoo = rb_define_module("Foo");
}
/* constants.c */
rb_define_const(mFoo, "VERSION", rb_str_new_cstr("1.0.0"));
In this shape, RDoc does not know what mFoo means while parsing constants.c, so Foo::VERSION is not documented.
There is partial cross-file support for _under definitions, such as:
/* bar.c */
VALUE cBar = rb_define_class_under(mFoo, "Bar", rb_cObject);
That can work because rb_define_class_under / rb_define_module_under goes through a store-backed enclosure lookup. In other words, when RDoc is creating a class or module, it has a special path that can sometimes find the enclosing C variable from another parsed file or cache.
Constants and methods do not appear to use the same path. They only check the parser-local @known_classes map, and if mFoo is missing, the entry is silently skipped.
A workaround is to add a fake seed comment in each C file:
/* RDoc parses C files independently: mFoo = rb_define_module("Foo") */
Because RDoc scans block comments for rb_define_* patterns, this seeds mFoo => Foo for that file and documentation is generated.
Expected behavior: once mFoo is defined in one parsed C file, later C files should be able to document constants and methods under Foo, or RDoc should provide a documented way to seed cross-file C namespace variables.
- 主要言語
- Ruby
- スター
- 930
- フォーク
- 465
- 平均マージ
- 2日 16時間
- マージ済み PR（30日）
- 28
環境構築
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
ruby/rdoc のほかの issue
-
RDoc 8.0.0 gem omits `doc/rdoc/example.rb`, which is referenced by the packaged markup documentationオープン
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 85/100
メンテナーはふだん 1 日以内に返信
-
enhancement
難易度 4/5 3〜5日 初心者へのやさしさ 68/100
メンテナーはふだん 1 日以内に返信
-
難易度 3/5 1〜2日 初心者へのやさしさ 68/100
メンテナーはふだん 1 日以内に返信
-
難易度 5/5 1週間以上 初心者へのやさしさ 35/100
メンテナーはふだん 1 日以内に返信
似ている issue
-
area/web interface
難易度 2/5 1〜3時間 初心者へのやさしさ 65/100
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1時間未満 初心者へのやさしさ 90/100
chef/mixlib-shellout#287 ·
-
難易度 2/5 1〜3時間 初心者へのやさしさ 88/100
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 86/100
-
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
メンテナーはふだん 1 日以内に返信