Project

General

Profile

Actions

Misc #17422

open

3.0 documentation problems tracking ticket

Added by zverok (Victor Shepelev) 10 months ago. Updated 10 months ago.

Status:
Open
Priority:
Normal
Assignee:
-
[ruby-core:101611]

Description

A meta-ticket for tracking all documentation problems with 3.0's new features (which hopefully should be fixed before the release). I plan to work on those myself, but I have only so much time, so the help would be appreciated.

  • Missing docs for new methods:
  • Method docs to be changed
    • Fiber#transfer changed limitations -- requires thorough redocumenting of #transfer, its use cases and limitations: https://github.com/ruby/ruby/pull/3981 merged
    • Module#include / #prepend -- I'd say the docs should be rewritten (now they are from the "internal" point of view), and only then there would be a place to describe the behavior change;
  • Larger chunks:
  • Should it be updated?
    • doc/syntax/assignment.rdoc -- "Class Variable" section, include more explanation on visibility (and new exceptions on "overtaking")?
    • Kernel#lambda -- include info on "only literal blocks"?
    • Symbol#to_proc -- explain about the block's lambdiness?
    • Mutex -- mention it is owned per-Fiber?
  • Documentation bugs:
    • Random lost definitions of instance methods: fixed by https://github.com/ruby/ruby/pull/3966 merged
    • Kernel: lost docs for several methods (like #abort, but also #exec, #exit) due to NO_RETURN macro, I am not yet sure how to fix it (moving comment before macro does not help)

To be continued...

Actions #1

Updated by zverok (Victor Shepelev) 10 months ago

  • Description updated (diff)

Updated by zverok (Victor Shepelev) 10 months ago

  • Description updated (diff)

Current status updated in ticket description. Of the critical (?) things before the release, I believe this is the most important:

  • Kernel: lost docs for several methods (like #abort, but also #exec, #exit) due to NORETURN macro, I am not yet sure how to fix it (moving comment before macro does not help).

Could be related to this commit in RDoc: "Exclude parenthesized function declarations such as NORETURN"

cc nobu (Nobuyoshi Nakada)

Updated by nobu (Nobuyoshi Nakada) 10 months ago

zverok (Victor Shepelev) wrote in #note-2:

  • Kernel: lost docs for several methods (like #abort, but also #exec, #exit) due to NORETURN macro, I am not yet sure how to fix it (moving comment before macro does not help).

That page is generated by RDoc 6.2.1.

Could be related to this commit in RDoc: "Exclude parenthesized function declarations such as NORETURN"

Yes, it intends to fix that issue, but isn't contained in older released versions of course.

Updated by zverok (Victor Shepelev) 10 months ago

nobu (Nobuyoshi Nakada) oh, good! I somehow assumed it always uses the rdoc bundled with the same version it documents.

Actions

Also available in: Atom PDF