ruby / ruby/rdoc

Wrong handling of File::Constants in Ruby core docs

Open
#741 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Ruby
Stars
930
Forks
465
Avg merge
3d 10h
Merged PRs (30d)
27

Description

There is a wrong representation of File::Constants module as a File::File::Constants: https://docs.ruby-lang.org/en/trunk/File/File/Constants.html.

I believe the root causes are:

I believe that maybe it is a sane solution (as RDoc is Ruby's standard library), to just remove the "hack" and document all the constants in file.c (maybe with help of #ifdef 0, if there is no way to move them completely.

I'm ready for any other suggestions, too (want to fix the inconsistency before Ruby 2.7).

PS: I am not sure if it is related (= if RDoc is used inside), but on ruby-doc.org there are also problems in representation: nesting seems right: https://ruby-doc.org/core-2.6.3/File/Constants.html, but File docs doesn't list the module.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with lib/rdoc/parser/c.rb around line 455, then inspect how dir.c and file.c are parsed and how their definitions produce the File::Constants documentation URL. Reproduce the generated documentation and trace why the module is nested as File::File::Constants or omitted from File.html. Done means the generated docs show the module at the correct nesting and list it from File.

Written by the indexing model from the issue text.

Assessment

Tech stack
c, ruby
Domain
documentation, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.