documenting-ruby / ruby Goto Github PK
View Code? Open in Web Editor NEWThis project forked from ruby/ruby
A concerted effort to augment and enhance Ruby MRI documentation
Home Page: http://documenting-ruby.org/
License: Other
This project forked from ruby/ruby
A concerted effort to augment and enhance Ruby MRI documentation
Home Page: http://documenting-ruby.org/
License: Other
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 :)
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.
I am planning on doing some documentation on the RSS::Atom module.
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.
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)
I expected that the sample code on a docs page should be valid for the particular version of Ruby I'm looking at.
IDK
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.)
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?
It could be cleaned up a bit.
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.
I'm making some minor changes to the pp class documentation.
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).
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
'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?
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
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.
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
I always wished the documentation was better here.
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.
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.
Clarification of differences between Object#clone and Object#dup
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.
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.)
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?
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)?
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'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 forIO
like
objects such asOpenSSL::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?
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"
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
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!!
I want to add documentation for Debug, which is currently lacking. I'll follow general recommendations for submitting patches, etc.
Work in progress
In Ruby >= 2.2, the following Hash literals are equivalent:
{ :my_key => 5 }
{ my_key: 5 }
{ :"my_key" => 5 }
{ :'my_key' => 5 }
{ "my_key": 5 }
{ 'my_key': 5 }
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.
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.
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
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?
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
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.
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
alias
in the current tree.Help?
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?
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
The documented example for find uses detect instead of find.
http://ruby-doc.org/core-2.2.3/Symbol.html#method-i-3D-3D-3D
Links to Symbol#==
instead which is listed twice
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.