Misc #18404: 3.1 documentation problems tracking ticket

• Status: Closed
• Assignee: -

[zverok (Victor Shepelev)]

So far, comparing the NEWS.md to actual documentation at https://docs.ruby-lang.org/en/master/, I identified the following problems:

• Random::Formatter: the explanations of how to use it are murky, examples do show just context-less examples like prng.hex(10)

Merged:

• Hash/keyword argument value omission—completely undocumented. PR: https://github.com/ruby/ruby/pull/5244 Merged
• Queue::new should be rewritten (bad rendering for example, non-informative parameter name). PR: https://github.com/ruby/ruby/pull/5273 Merged
• Thread::Backtrace.limit isn't mentioned anywhere (Thread::Backtrace doesn't even have its own page, only Thread::Backtrace::Location has). PR: https://github.com/ruby/ruby/pull/5305 Merged
• Fiber::SchedulerInterface
  — no docs for new methods supported: address_resolve, timeout_after, io_read, io_write. PR: https://github.com/ruby/ruby/pull/5280 Merged
• New Refinement class has no docs whatsoever. PR: https://github.com/ruby/ruby/pull/5272 Merged
• Struct: #keyword_init? isn't mentioned anywhere. PR: https://github.com/ruby/ruby/pull/5279 Merged
• GC: ::measure_total_time, ::measure_total_time=, ::total_time isn't mentioned anywhere. UPD: was just a documentation rendering glitch, PR: https://github.com/ruby/ruby/pull/5306 Merged
• String#unpack and #unpack1: new offset param examples are given too early, before the main examples. unpack1 also has code formatting glitch. PR: https://github.com/ruby/ruby/pull/5331 Merged
• Marshal#load: the new parameter freeze: is not documented. PR: https://github.com/ruby/ruby/pull/5332 Merged
• IO::Buffer no docs. PR: https://github.com/ruby/ruby/pull/5302 Merged by hand by @ioquatix (Samuel Williams)

Small glitches in new docs:

• Process._fork formatting of tt. PR: https://github.com/ruby/ruby/pull/5270 Merged
• Integer#try_convert: small typo: "Returns nil if object does not respond to :to_ary" (should be :to_int). Fixed already.

I'll try to address as much as I'll be able myself, but if some of the feature authors/other volunteers are willing to participate, I'll be glad :)

The ticket might be expanded if I'll notice something else.

[ioquatix (Samuel Williams)]

IO::Buffer is also totally undocumented.

[zverok (Victor Shepelev)]

@ioquatix (Samuel Williams) oh, indeed. And new methods that can/should be supported by the scheduler aren't yet in the SchedulerInterface :(

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

[matheusrich (Matheus Richard)]

@zverok (Victor Shepelev) LMK if I can help you. I'm available @matheusrich (Matheus Richard) on Twitter.

[zverok (Victor Shepelev)]

@matheusrich (Matheus Richard) if you are willing to participate, let's coordinate efforts here for better visibility :)

Are you willing to write some docs yourself? You'll need to fork ruby repo, make a local branch, fix docs, check them locally (you can run rdoc -o _rdoc_test to render them into a separate folder; you also can run rdoc some_file.c -o rdoc_test to render them quicker from only one file), and then make a PR to the original repo.

Which part you'd like to handle?

[matheusrich (Matheus Richard)]

I wanna take the easiest one (documenting Struct#keyword_init) to get my feet wet.

[matheusrich (Matheus Richard)]

I can also tackle the small glitches/typos you last mentioned.

[zverok (Victor Shepelev)]

@matheusrich (Matheus Richard) That would be awesome! Thanks!

[matheusrich (Matheus Richard)]

First PR is out: PR #5268 (merged) Improves Integer.try_convert docs

[matheusrich (Matheus Richard)]

Fix docs rendering for Process._fork #5270 (merged)

[matheusrich (Matheus Richard)]

@zverok (Victor Shepelev) there's a reference to keyword_init on Struct here (if the link doesn't work, it's right above "Public Instance Methods"). Am I missing something?

[zverok (Victor Shepelev)]

@matheusrich (Matheus Richard) I'll look into the PRs in a few hours, thanks! About Struct: we need documentation for this method:

MyStruct = Struct.new(:a, :b, keyword_init: true)
# => MyStruct(keyword_init: true) 
MyStruct.keyword_init? # <=== this one
# => true 

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

[matheusrich (Matheus Richard)]

Gotcha! Thanks. I couldn't make it show up on the docs, though.

The docs are definitely there (struct.c:288)

/*
 * call-seq:
 *   StructClass.keyword_init? -> true or false
 *
 * Returns true if the class was initialized with +keyword_init: true+.
 * Otherwise returns false.
 *
 * Examples:
 *   Foo = Struct.new(:a)
 *   Foo.keyword_init? # => nil
 *   Bar = Struct.new(:a, keyword_init: true)
 *   Bar.keyword_init? # => true
 *   Baz = Struct.new(:a, keyword_init: false)
 *   Baz.keyword_init? # => false
 */
#define rb_struct_s_keyword_init_p rb_struct_s_keyword_init

I'm not super familiar with C, so I may be missing something. I wonder if the docs are not present because this method
is defined on the singleton class, not on the Struct class itself. If that's the case, maybe we can just add
a reference to it on the Keyword Argument section.

[zverok (Victor Shepelev)]

OK, I'll try to fight it, there are quite a few weird tricks that might help

[matheusrich (Matheus Richard)]

On another semi-unrelated note, isn't weird that this method returns nil sometimes (e.g. Struct.new(:a).keyword_init? # => nil)?
Is there any precedence for a question mark method returning nil? I know nil is falsey, but this might be confusing.

Edit: looks like File.size? does that.

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

Folks, maybe that's not obvious but I don't have commit rights.
So, unless somebody merges the PRs that are listed above—the docs for those features will be missing.

cc @nobu (Nobuyoshi Nakada) (I don't know who else I should tag, please advise)

[zverok (Victor Shepelev)]

• Description updated (diff)

[zverok (Victor Shepelev)]

• Status changed from Open to Closed