Project

General

Profile

Actions

Misc #18404

open

3.1 documentation problems tracking ticket

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

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

Description

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:

Small glitches in new docs:

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.

Updated by ioquatix (Samuel Williams) 5 months ago

IO::Buffer is also totally undocumented.

Updated by zverok (Victor Shepelev) 5 months ago

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

Actions #3

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions #4

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)

Updated by zverok (Victor Shepelev) 5 months ago

@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?

Updated by matheusrich (Matheus Richard) 5 months ago

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

Updated by matheusrich (Matheus Richard) 5 months ago

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

Updated by matheusrich (Matheus Richard) 5 months ago

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

Updated by matheusrich (Matheus Richard) 5 months ago

@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?

Updated by zverok (Victor Shepelev) 5 months ago

@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 
Actions #14

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions #15

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions #16

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)

Updated by matheusrich (Matheus Richard) 5 months ago

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.

Updated by zverok (Victor Shepelev) 5 months ago

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

Updated by matheusrich (Matheus Richard) 5 months ago

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.

Actions #20

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions #21

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions #22

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions #23

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions #24

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions #25

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions #26

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions #27

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions #28

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions #29

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions #30

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions #31

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)

Updated by zverok (Victor Shepelev) 5 months ago

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)

Actions #33

Updated by zverok (Victor Shepelev) 5 months ago

  • Description updated (diff)
Actions

Also available in: Atom PDF