ruby / ruby/rdoc

Documenting `Data` classes

Open
#1,375 0 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

rdoc does not usefully document data classes defined the correct way:

# Documenting a class made with Data.define
MyDataClass = Data.define :a do
  # Capitalize the value of +a+.
  def cap
    a.capitalize
  end
end

This documents a constant on Object, Object::MyDataClass instead of documenting it as a class itself, and the method within the data class definition is not documented either. It does not matter whether the Prism parser is used.

When documented with reopening, there are two different issues

MyDataClass = Data.define :a # :nodoc:

# Documenting a class made with Data.define
class MyDataClass
  # Capitalize the value of +a+.
  def cap
    a.capitalize
  end
end

If defined without # :nodoc:, MyDataClass is still documented as a constant on Object; if defined with # :nodoc:, the documentation is removed, but the generated documentation pages for Object isn't removed.

I believe that Data.define and Struct.new should be treated as if they were written as class variants.

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 by reproducing the documented examples using rdoc, with and without the Prism parser, for Data.define, Struct.new, and reopening the generated class. Trace how these definitions are classified and verify that the class and its methods are documented as a class, while stale Object documentation is not retained.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.