Hi, I wanted to see if I could help fill in the docs for shell. A lot of the classes in that namespace don't have descriptions for their methods yet.

Has someone else prioritized this or can I go ahead?

Also I'd like to know where you would prefer people to offer documentation when they do... In this repo? In the main Ruby repo on github? I've seen people do both. Thanks!!

On http://ruby-doc.org/core-2.2.2/Hash.html#method-i-store, the notation { my_key: 5 } (available since Ruby 1.9) is introduced with

Hashes allow an alternate syntax form when your keys are always symbols.

(Emphasis mine.)

This suggests that this syntax will only be allowed for literals of Hashes where all keys are are Symbols. However, experiments show it works fine for Hashes of mixed key types:

{"a string" => 1, a_symbol: 2, Math::PI => 3 }

(Of course, the colon syntax can only be used for those keys that are Symbols.)

http://ruby-doc.org/stdlib-2.3.0/libdoc/logger/rdoc/Logger.html#new-method

From only looking at the docs, it's not obvious what the default value is for shift_age, nor what value disables the option. The only way to find out is to look at the code itself.

Can submit a PR with the following adjustment: trunk...spacemunkay:specify-logger-shift-age-default

http://ruby-doc.org/core-2.2.3/Symbol.html#method-i-3D-3D-3D

Links to Symbol#== instead which is listed twice

At http://documenting-ruby.org/ it says that documentation issues should be opened at https://github.com/documenting-ruby/ruby/issues/new

But when I visit https://github.com/documenting-ruby/ruby/issues/new, there is a message above the submission form: "Please review the guidelines for contributing to this repository." That link goes to a page directing me to open issues at https://bugs.ruby-lang.org.

It seems to me that documentation issues really are supposed to be logged here, not at https://bugs.ruby-lang.org, right? Is it possible to change the "Please review the guidelines for contributing to this repository." message in this fork? Maybe the link could go to http://documenting-ruby.org/ instead?

I just searched the web for "ruby StringIO" and landed on the 1.9.3 documentation. I wanted to see the StringIO docs for a version >= 2.0. There is currently no easy way to get from one to the other, and no way to predict which version a search engine will find first.

Could we add a dropdown on each doc page, linking to the corresponding page for other versions of Ruby? If there are too many, maybe it could be limited to the most recent N releases, or the the most recent N on each branch.

This says that #map returns an_enumerator and a new array:

http://ruby-doc.org/core-2.4.0/Enumerable.html#method-i-map

irb says:

irb(main):002:0> [1,2,3].map {|x| x+1}.class
=> Array
irb(main):003:0> [1,2,3].lazy.map {|x| x+1}.class
=> Enumerator::Lazy

and Lazy docs says nothing about behaving differently.

and i can be hallucinating, but i remember seeing different things about #map and #collect on this page, saying that #map would return enumerator and #collect would return array.

<3

Hi!

I noticed that the Symbol Public Instance Method == was duplicated in the ruby-docs site. I checked the string.c file in the documenting-ruby/ruby repo, but it does not seem duplicated there. Perhaps an issue occurs in the generation of the documentation? Attached is a screenshot.

Let me know if I can do anything!

Kindly,
Emily

We had an issue where we had to figure out a way to make the following command work through Ruby's stdlib:

echo | openssl s_client -connect google.com:443 -servername google.com 2>/dev/null | openssl x509 -noout -fingerprint

Note the -servername option

I spent a lot of time looking around, first looking at the servername_cb callback (which in itself is poorly documented if at all), only later realizing there's a hostname attribute on OpenSSL::SSL::SSLContext

In case you're not familiar with the servername option, it's used to get the correct certificate on a domain name where the host uses Server Name Indication or SNI in short.

Work in progress

http://ruby-doc.org/core-2.2.2/_lib/racc/rdoc/grammar_en_rdoc.html#label-Class+Block

The collect and map documentation are the same, and show examples of each to enforce this. There's no mention however that they are aliases for the same code (but that's another issue for later).

However the collect_concat and flat_map documentation only shows examples of code using flat_map. There's no mention that these one is an alias for another, and the example never shows collect_concat.

I propose (and will file a PR) that we have one example of collect_concat and one of flat_map to demonstrate that these are the same. Otherwise, looking at the documentation for collect_concat and not seeing a code example of it being used is confusing and inconsistent.

I'd like to add code examples to the documentation for OpenSSL::HMAC. I had to use it recently and want to help make its usage more obvious. Is this up for grabs?

The Dir.children method was added to Ruby trunk with Feature #11302. It was however not backported to Ruby 2.4 yet. Attempting to use it results in a NoMethodError in Ruby.

However, the method documentation is added to the Ruby 2.4.1 documentation at https://ruby-doc.org/core-2.4.1/Dir.html#method-c-children. Why is this the case? The method is not part of Ruby 2.4 and is (as far as I can see) not mentioned in the source code.

This was also asked and investigated at https://stackoverflow.com/a/45719685/421705

I always wished the documentation was better here.

This doesn't really scan:

Clearly the idea is to suggest the use of Forwardable as an alternative to classical inheritance, but it doesn't come across very clearly.

Clarification of differences between Object#clone and Object#dup

I was trying to explain puts to someone, and noticed that the documentation says that puts is "equivalent to $stdout.puts" That led me to try and track down where to explain what $stdout refers to but I couldn't find any obvious place to add it in... I'd imagine it'd have to be somewhere in a list of "default Ruby global variables," but it isn't clear to me where that should be.

Should the documentation for IO be the place to list at least global variables of that class?

Since Ruby 2.0, \X matches a grapheme cluster as defined by unicode. It can basically be thought of as a unicode-aware . (takes into account combining characters, etc.)

String#delete_prefix and String#delete_prefix! appear in the documentation for Ruby 2.4.1, but when I try to use them I get the following error:

"hello".delete_prefix("hel")
NoMethodError: undefined method `delete_prefix' for "hello":String
	from (irb):1
	from /Users/alex/.rbenv/versions/2.4.1/bin/irb:11:in `<main>'

These work properly in 2.5.0dev:

"hello".delete_prefix("hel")
=> "lo"

Paragraph documenting it is clunky and hard to digest. Especially because of references to three different global variables. It could do some work by separating it into smaller ones to provide some clarity.

The documented example for find uses detect instead of find.

http://ruby-doc.org/docs/keywords/1.9 incorrectly states that arguments to alias can be String. See rubocop/rubocop#657. I spent a long time trying to figure out whether

• This is still an issue in the current documentation. I cannot for the life of me find the doc for alias in the current tree.
• How to fix this for 1.9.x.

Help?

Document cases in Ruby Core where Ruby classes will implicitly send messages like #to_str or #to_ary to objects they are given, in order to ensure they are working with the expected type.

This documentation will help programmers identify which methods are needed in their classes in order that they 'quack' like Ruby Core classes such as File (e.g., by providing a #to_path method).

In this case I would add documentation and perhaps an example about this to http://ruby-doc.org/core-2.3.3/File.html.

The ruby repository fork in this org is quite old, currently 7156 commits behind master.

The how-to instructions mention how to clone this repository to add docs patches.

If a user follows those instructions, they're perhaps wasting effort: the upstream may have moved on.

As in the Array ruby docs, identical methods are listed as "Alias for: method name". For example in the Array docs there are two identical methods: length, and size. It is indicated that in both methods that they Alias for: length and Alias for: size. This is very helpful to the Dev in that it is immediately known that both methods act the exact same way when used; more over, that either method can be used safely knowing the outcome, just adding more linguistic control over code read.

'Supplemental notes' sections break fragment identifier navigation

There are 'Supplemental notes' sections on some documentation pages that load a second or two after the rest of the page loads. When they appear, they bump down all the content below them. This causes links that include a fragment identifier for a particular section, like documentation for a method, to become much less usable, because when the page finishes loading the section has moved down the page, possibly even out of view.

For example if you visit http://ruby-doc.org/core-2.1.5/String.html#method-i-to_i and wait for the page to load, the to_i method documentation will initially be at the top of the window, but when the supplemental notes sections subsequently load, the to_i documentation jumps down the page out of view.

I haven't been able to find any supplemental notes sections for Ruby 2.2.4. Have supplemental notes been removed from newer versions of the documentation?

If not, is it possible to have the supplemental notes load along with the rest of the page, or somehow realign the window with the correct section after the supplemental notes load?

It could be cleaned up a bit.

This method isn't in the Regexp or String documentation:

Ruby 2.1.2 Regexp: http://ruby-doc.org/core-2.1.2/doc/regexp_rdoc.html
Ruby 2.2.2 Regexp: http://ruby-doc.org/core-2.2.2/Regexp.html
Ruby 2.2.0 String: http://ruby-doc.org/core-2.2.0/String.html

Was great to meet @zzak at BrightonRuby Conf, thanks for the inspiration to start working on documenting Ruby.

I've run rdoc for a list of undocumented areas and I've picked the DEBUGGER__ Class. If there are any reasons why DEBUGGER__ is a bad choice please let me know. Otherwise a PR should follow soon :)

http://documenting-ruby.org/step-by-step-guide.html is quite prominent result for googling about ruby documentation.

It would be useful to describe it as dead on its landing page give activity here (no response to PR since 2014 etc).

I've been looking for ways to make some of the existing documentation easier to read. Looking through io.c, I noticed the comment for IO.select currently says

Especially, the combination of nonblocking methods and
IO.select is preferred for IO like
objects such as OpenSSL::SSL::SSLSocket.

It then goes on to explain several reasons why that could be a bad idea. Is it really preferred as long as you account for those potential problems, or did someone leave out a word when writing this documentation?

There some miss-match quote pairs in some class like, Time Class, and few others, example: (``Sunday'') (start with double back-tick and end with double single quotes.

what are the diffrence between fetch,at,slice and index metods in ruby? pleae anyone explain me with example.
and also help me to strong in the ruby on rails.

io/nonblock in the standard library looks undocumented so far. Looking at nonblock.c and playing with it in IRB shows it defines 3 methods on IO objects when it's required. Is this available for me to work on?

I want to add documentation for Debug, which is currently lacking. I'll follow general recommendations for submitting patches, etc.

https://ruby-doc.org/core-2.6.1/Marshal.html#top

This example:

class MyObj
def initialize name, version, data
@name = name
@Version = version
@DaTa = data
end

def _dump level
[@name, @Version].join ':'
end

def self._load args
new(*args.split(':'))
end
end

Should be like this:

class MyObj
def initialize name, version, data
@name = name
@Version = version
@DaTa = data
end

def _dump level
[@name, @Version,@DaTa].join ':'
end

def self._load args
new(*args.split(':'))
end
end

In both 1.9.3 and 2.0 documentation, the Regexp#== documentation contains invalid examples

http://www.ruby-doc.org/core-1.9.3/Regexp.html#method-i-3D-3D
http://www.ruby-doc.org/core-2.0/Regexp.html#method-i-3D-3D

/abc/  == /abc/   #=> false
/abc/  == /abc/   #=> false
/abc/  == /abc/   #=> false
/abc/ == /abc/   #=> false

The examples appear to be correct on github however

https://github.com/documenting-ruby/ruby/blob/trunk/re.c#L2609

Hey y'all, so I wanted to try submitting my first patch to Ruby and I thought documentation would be a good way to start.

For now I am trying to document #thread_list_all().

I hope to document more of the class but I wanted to start small to get the process down.

I'm making some minor changes to the pp class documentation.

As near as I can tell, using parentheses to override precedence in expressions isn't mentioned anywhere in the docs. I think this maybe belongs on the precedence.rdoc page; I'm willing to write a patch for this, but since this would be my first, I wanted to check with the documentation crew that the documentation truly isn't there.

What is the problem?

On this page, It shows the following example code:

builder = Psych::Visitors::YAMLTree.new
builder << { :foo => 'bar' }
builder.tree # => #<Psych::Nodes::Stream .. }

This seems to work up until 2.4.0. In 2.5.0+, it seems that the optional parameters for new became mandatory:

pry(main)> builder = Psych::Visitors::YAMLTree.new
ArgumentError: wrong number of arguments (given 0, expected 3)

What was the expected behaviour?

I expected that the sample code on a docs page should be valid for the particular version of Ruby I'm looking at.

If you have an idea for a potential fix, list it here

IDK

When I search for some method on ruby-doc, I miss an information about aliases for a method, like on Enumerable module: select is an alias to find_all, but I can't know that when I read the documentation (except when I click "toggle source" and realize that both show the same code).
Is there a solution to show that information (other than adding on find_all doc something like "select" and "find_all" are aliases)?

I am planning on doing some documentation on the RSS::Atom module.

In Ruby >= 2.2, the following Hash literals are equivalent:

1. { :my_key => 5 }
   
   (Symbol literal used as key in the generic hash literal notation that'd work for non-Symbol keys, too.)
2. { my_key: 5 }
   
   (Symbol-key-specific "JavaScript-like" new notation introduced in Ruby 1.9)
3. { :"my_key" => 5 }
   
   (Same as (1.), just with a different notation for the Symbol literal. Allows string interpolation inside the symbol name.)
4. { :'my_key' => 5 }
   
   (Same as (1.), just with a different notation for the Symbol literal. No string interpolation.)
5. { "my_key": 5 }
   
   (Introduced by feature request #4276 in Ruby 2.2. Allows string interpolation inside the symbol name.)
6. { 'my_key': 5 }
   
   (Probably also introduced by feature request ruby#4276. No string interpolation.)

While (1.) & (2.) are documented on http://ruby-doc.org/core-2.2.2/Hash.html and (3.) & (4.) follow from (1.) when plugging in the alternate Symbol literal notations, (5.) & (6.) seem to be undocumented yet.