C parser drops docs under namespace variables defined in another file
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 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 查找进行比较。使用双文件 mFoo 示例验证行为：在另一个文件中定义、位于 mFoo 之后的常量和方法应出现在 Foo 下，而不需要伪造的 seed 注释。
由索引模型根据 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 天 3 小时
- 30 天内合并 PR
- 25
环境准备
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 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 一周以上 新手友好度 35/100
维护者通常 1 天内回复
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 90/100
维护者通常 3 天内回复
-
enhancement
难度 2/5 1-3 小时 新手友好度 68/100
维护者通常 2 天内回复
-
难度 2/5 1-3 小时 新手友好度 85/100
jetrockets/jet_ui#47 ·
-
难度 2/5 1-3 小时 新手友好度 84/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 76/100
FreeCAD/homebrew-freecad#870 ·
维护者通常 1 天内回复