Project

General

Profile

Misc #17422

3.0 documentation problems tracking ticket

Added by zverok (Victor Shepelev) 3 months ago. Updated 2 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...

#1

Updated by zverok (Victor Shepelev) 2 months ago

  • Description updated (diff)

Updated by zverok (Victor Shepelev) 2 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) 2 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) 2 months ago

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

Also available in: Atom PDF