From 4f94cb43fcf7035e7ee1db0ba6750d3249567085 Mon Sep 17 00:00:00 2001 From: hsbt Date: Fri, 18 Dec 2015 03:39:49 +0000 Subject: [PATCH] * doc/syntax/*.rdoc: separated modifier at sentence. [ci skip][fix GH-1121] Patch by @clandry94 git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@53182 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 5 +++++ doc/syntax/assignment.rdoc | 9 ++++----- doc/syntax/calling_methods.rdoc | 21 ++++++++++----------- doc/syntax/control_expressions.rdoc | 25 ++++++++++++------------- doc/syntax/exceptions.rdoc | 7 +++---- doc/syntax/literals.rdoc | 6 +++--- doc/syntax/methods.rdoc | 13 ++++++------- doc/syntax/miscellaneous.rdoc | 11 +++++------ doc/syntax/modules_and_classes.rdoc | 5 ++--- doc/syntax/refinements.rdoc | 1 - 10 files changed, 50 insertions(+), 53 deletions(-) diff --git a/ChangeLog b/ChangeLog index b79c3d1bc5..7c998c6257 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Fri Dec 18 12:39:42 2015 SHIBATA Hiroshi + + * doc/syntax/*.rdoc: separated modifier at sentence. + [ci skip][fix GH-1121] Patch by @clandry94 + Fri Dec 18 12:09:21 2015 Nobuyoshi Nakada * ext/stringio/stringio.c (strio_ungetbyte): pad with \000 when diff --git a/doc/syntax/assignment.rdoc b/doc/syntax/assignment.rdoc index adfe6485a4..83300cbece 100644 --- a/doc/syntax/assignment.rdoc +++ b/doc/syntax/assignment.rdoc @@ -1,6 +1,6 @@ = Assignment -In Ruby assignment uses the = (equals sign) character. This +In Ruby, assignment uses the = (equals sign) character. This example assigns the number five to the local variable +v+: v = 5 @@ -137,7 +137,7 @@ Here is an example of instance variable usage: p object2.value # prints "other value" An uninitialized instance variable has a value of +nil+. If you run Ruby with -warnings enabled you will get a warning when accessing an uninitialized +warnings enabled, you will get a warning when accessing an uninitialized instance variable. The +value+ method has access to the value set by the +initialize+ method, but @@ -279,7 +279,7 @@ to an instance variable most people use Module#attr_accessor: end When using method assignment you must always have a receiver. If you do not -have a receiver Ruby assumes you are assigning to a local variable: +have a receiver, Ruby assumes you are assigning to a local variable: class C attr_accessor :value @@ -409,7 +409,7 @@ You can use multiple assignment to swap two values in-place: # prints {:new_value=>1, :old_value=>2} If you have more values on the right hand side of the assignment than variables -on the left hand side the extra values are ignored: +on the left hand side, the extra values are ignored: a, b = 1, 2, 3 @@ -452,4 +452,3 @@ Since each decomposition is considered its own multiple assignment you can use p a: a, b: b, c: c, d: d # prints {:a=>1, :b=>2, :c=>[3, 4], :d=>[5, 6]} - diff --git a/doc/syntax/calling_methods.rdoc b/doc/syntax/calling_methods.rdoc index 99ec48af40..f1ebf186f7 100644 --- a/doc/syntax/calling_methods.rdoc +++ b/doc/syntax/calling_methods.rdoc @@ -66,7 +66,7 @@ The positional arguments for the message follow the method name: my_method(argument1, argument2) -In many cases parenthesis are not necessary when sending a message: +In many cases, parenthesis are not necessary when sending a message: my_method argument1, argument2 @@ -88,7 +88,7 @@ hash-type arguments are assigned as a single hash to the last argument: my_method('a' => 1, b: 2) # prints: {'a'=>1, :b=>2} -If too many positional arguments are given an ArgumentError is raised. +If too many positional arguments are given, an ArgumentError is raised. === Default Positional Arguments @@ -250,8 +250,8 @@ Both are equivalent to: my_method(1, 2, 3) -If the method accepts keyword arguments the splat operator will convert a hash -at the end of the array into keyword arguments: +If the method accepts keyword arguments, the splat operator will convert a +hash at the end of the array into keyword arguments: def my_method(a, b, c: 3) end @@ -263,7 +263,7 @@ You may also use the ** (described next) to convert a Hash into keyword arguments. If the number of objects in the Array do not match the number of arguments for -the method an ArgumentError will be raised. +the method, an ArgumentError will be raised. If the splat operator comes first in the call, parentheses must be used to avoid a warning. @@ -290,7 +290,7 @@ Both are equivalent to: my_method(first: 3, second: 4, third: 5) If the method definition uses ** to gather arbitrary keyword -arguments they will not be gathered by *: +arguments, they will not be gathered by *: def my_method(*a, **kw) p arguments: a, keywords: kw @@ -302,7 +302,7 @@ Prints: {:arguments=>[1, 2, {"3"=>4}], :keywords=>{:five=>6}} -Unlike the splat operator described above the ** operator has no +Unlike the splat operator described above, the ** operator has no commonly recognized name. === Proc to Block Conversion @@ -323,12 +323,12 @@ operator: If the splat operator comes first in the call, parenthesis must be used to avoid a warning. -Unlike the splat operator described above the & operator has no +Unlike the splat operator described above, the & operator has no commonly recognized name. == Method Lookup -When you send a message Ruby looks up the method that matches the name of the +When you send a message, Ruby looks up the method that matches the name of the message for the receiver. Methods are stored in classes and modules so method lookup walks these, not the objects themselves. @@ -347,7 +347,6 @@ If no match is found this repeats from the beginning, but looking for +method_missing+. The default +method_missing+ is BasicObject#method_missing which raises a NameError when invoked. -If refinements (an experimental feature) are active the method lookup changes. +If refinements (an experimental feature) are active, the method lookup changes. See the {refinements documentation}[rdoc-ref:syntax/refinements.rdoc] for details. - diff --git a/doc/syntax/control_expressions.rdoc b/doc/syntax/control_expressions.rdoc index 76ca3b47be..123b48b6b9 100644 --- a/doc/syntax/control_expressions.rdoc +++ b/doc/syntax/control_expressions.rdoc @@ -110,7 +110,7 @@ expression as this can be confusing. == +unless+ Expression The +unless+ expression is the opposite of the +if+ expression. If the value -is false the "then" expression is executed: +is false, the "then" expression is executed: unless true puts "the value is a false-value" @@ -204,10 +204,10 @@ Here is an example of using +case+ to compare a String against a pattern: Here the string "12345" is compared with /^1/ by calling /^1/ === "12345" which returns +true+. Like the +if+ -expression the first +when+ that matches is executed and all other matches are +expression, the first +when+ that matches is executed and all other matches are ignored. -If no matches are found the +else+ is executed. +If no matches are found, the +else+ is executed. The +else+ and +then+ are optional, this +case+ expression gives the same result as the one above: @@ -300,9 +300,9 @@ This prints the numbers 0 through 11. Like a while loop the condition a > 10 is checked when entering the loop and each time the loop body executes. If the condition is false the loop will continue to execute. -Like a +while+ loop the +do+ is optional. +Like a +while+ loop, the +do+ is optional. -Like a +while+ loop the result of an +until+ loop is nil unless +break+ is +Like a +while+ loop, the result of an +until+ loop is nil unless +break+ is used. == +for+ Loop @@ -356,7 +356,7 @@ before the condition: p a # prints 10 -If you don't use +rescue+ or +ensure+ Ruby optimizes away any exception +If you don't use +rescue+ or +ensure+, Ruby optimizes away any exception handling overhead. == +break+ Statement @@ -434,7 +434,7 @@ Use +redo+ to redo the current iteration: This prints [0, 1, 3, 3, 5, 5, 7, 7, 9, 9, 11] -In Ruby 1.8 you could also use +retry+ where you used +redo+. This is no +In Ruby 1.8, you could also use +retry+ where you used +redo+. This is no longer true, now you will receive a SyntaxError when you use +retry+ outside of a +rescue+ block. See {Exceptions}[rdoc-ref:syntax/exceptions.rdoc] for proper usage of +retry+. @@ -461,14 +461,14 @@ Here is an example: p selected # prints [2, 3, 4, 5, 6, 7, 8] -In the above example the on condition is n==2. The flip-flop +In the above example, the on condition is n==2. The flip-flop is initially off (false) for 0 and 1, but becomes on (true) for 2 and remains on through 8. After 8 it turns off and remains off for 9 and 10. The flip-flop must be used inside a conditional such as +if+, +while+, +unless+, +until+ etc. including the modifier forms. -When you use an inclusive range (..) the off condition is +When you use an inclusive range (..), the off condition is evaluated when the on condition changes: selected = [] @@ -479,11 +479,11 @@ evaluated when the on condition changes: p selected # prints [2] -Here both sides of the flip-flop are evaluated so the flip-flop turns on and +Here, both sides of the flip-flop are evaluated so the flip-flop turns on and off only when +value+ equals 2. Since the flip-flop turned on in the iteration it returns true. -When you use an exclusive range (...) the off condition is +When you use an exclusive range (...), the off condition is evaluated on the following iteration: selected = [] @@ -494,7 +494,6 @@ evaluated on the following iteration: p selected # prints [2, 3, 4, 5] -Here the flip-flop turns on when +value+ equals 2 but doesn't turn off on the +Here, the flip-flop turns on when +value+ equals 2, but doesn't turn off on the same iteration. The off condition isn't evaluated until the following iteration and +value+ will never be two again. - diff --git a/doc/syntax/exceptions.rdoc b/doc/syntax/exceptions.rdoc index 0efc35a59f..a2e75616fb 100644 --- a/doc/syntax/exceptions.rdoc +++ b/doc/syntax/exceptions.rdoc @@ -8,7 +8,7 @@ Exceptions are rescued in a +begin+/+end+ block: # handle exception end -If you are inside a method you do not need to use +begin+ or +end+ unless you +If you are inside a method, you do not need to use +begin+ or +end+ unless you wish to limit the scope of rescued exceptions: def my_method @@ -29,7 +29,7 @@ variable_name at the end of the +rescue+ line: raise # re-raise the current exception end -By default StandardError and its subclasses are rescued. You can rescue a +By default, StandardError and its subclasses are rescued. You can rescue a specific set of exception classes (and their subclasses) by listing them after +rescue+: @@ -52,7 +52,7 @@ You may rescue different types of exceptions in different ways: end The exception is matched to the rescue section starting at the top, and matches -only once. If an ArgumentError is raised in the begin section it will not be +only once. If an ArgumentError is raised in the begin section, it will not be handled in the StandardError section. You may retry rescued exceptions: @@ -93,4 +93,3 @@ You may also run some code when an exception is not raised: ensure # ... end - diff --git a/doc/syntax/literals.rdoc b/doc/syntax/literals.rdoc index 9631575320..f5b9738868 100644 --- a/doc/syntax/literals.rdoc +++ b/doc/syntax/literals.rdoc @@ -133,7 +133,7 @@ You may also create strings using %: %(1 + 1 is #{1 + 1}) #=> "1 + 1 is 2" There are two different types of % strings %q(...) behaves -like a single-quote string (no interpolation or character escaping) while +like a single-quote string (no interpolation or character escaping), while %Q behaves as a double-quote string. See Percent Strings below for more discussion of the syntax of percent strings. @@ -259,7 +259,7 @@ Like strings, a single-quote may be used to disable interpolation: :'my_symbol#{1 + 1}' #=> :"my_symbol\#{1 + 1}" -When creating a Hash there is a special syntax for referencing a Symbol as +When creating a Hash, there is a special syntax for referencing a Symbol as well. == Arrays @@ -344,7 +344,7 @@ This proc will add one to its argument. == Percent Strings -Besides %(...) which creates a String, The % may create +Besides %(...) which creates a String, the % may create other types of object. As with strings, an uppercase letter allows interpolation and escaped characters while a lowercase letter disables them. diff --git a/doc/syntax/methods.rdoc b/doc/syntax/methods.rdoc index c8fc584c68..0ee2a08367 100644 --- a/doc/syntax/methods.rdoc +++ b/doc/syntax/methods.rdoc @@ -52,18 +52,18 @@ executed just like any other method. However, by convention, a method with an exclamation point or bang is considered dangerous. In ruby core library the dangerous method implies that when a method ends with a bang (!), it indicates that unlike its non-bang equivalent, permanently modifies its -receiver. Almost always, Ruby core library will have a non-bang +receiver. Almost always, ruby core library will have a non-bang counterpart (method name which does NOT end with !) of every bang method (method name which does end with !) that does not modify the receiver. This convention is typically true for ruby core library but may or may not hold true for other ruby libraries. -Methods that end with a question mark by convention return boolean. But they -may not always return just +true+ or +false+. Often they will may return an +Methods that end with a question mark by convention return boolean, but they +may not always return just +true+ or +false+. Often, they will return an object to indicate a true value (or "truthy" value). Methods that end with an equals sign indicate an assignment method. For -assignment methods the return value is ignored, the arguments are returned +assignment methods, the return value is ignored and the arguments are returned instead. These are method names for the various ruby operators. Each of these @@ -148,7 +148,7 @@ evaluated. end Note that for assignment methods the return value will always be ignored. -Instead the argument will be returned: +Instead, the argument will be returned: def a=(value) return 1 + value @@ -450,7 +450,6 @@ May be written as: # handle exception end -If you wish to rescue an exception for only part of your method use +begin+ and +If you wish to rescue an exception for only part of your method, use +begin+ and +end+. For more details see the page on {exception handling}[rdoc-ref:syntax/exceptions.rdoc]. - diff --git a/doc/syntax/miscellaneous.rdoc b/doc/syntax/miscellaneous.rdoc index 8f424f019f..d5691f8d60 100644 --- a/doc/syntax/miscellaneous.rdoc +++ b/doc/syntax/miscellaneous.rdoc @@ -10,16 +10,16 @@ most frequently used with ruby -e. == Indentation -Ruby does not require any indentation. Typically ruby programs are indented +Ruby does not require any indentation. Typically, ruby programs are indented two spaces. -If you run ruby with warnings enabled and have an indentation mis-match you +If you run ruby with warnings enabled and have an indentation mis-match, you will receive a warning. == +alias+ The +alias+ keyword is most frequently used to alias methods. When aliasing a -method you can use either its name or a symbol: +method, you can use either its name or a symbol: alias new_name old_name alias :new_name :old_name @@ -61,7 +61,7 @@ You may use +undef+ in any scope. See also Module#undef_method p defined?(RUBY_VERSION) # prints "constant" p defined?(1 + 1) # prints "method" -You don't need to use parenthesis with +defined?+ but they are recommended due +You don't need to use parenthesis with +defined?+, but they are recommended due to the {low precedence}[rdoc-ref:syntax/precedence.rdoc] of +defined?+. For example, if you wish to check if an instance variable exists and that the @@ -69,7 +69,7 @@ instance variable is zero: defined? @instance_variable && @instance_variable.zero? -This returns "expression" which is not what you want if the +This returns "expression", which is not what you want if the instance variable is not defined. @instance_variable = 1 @@ -104,4 +104,3 @@ Here is an example one-liner that adds numbers from standard input or any files in the argument list: ruby -ne 'BEGIN { count = 0 }; END { puts count }; count += gets.to_i' - diff --git a/doc/syntax/modules_and_classes.rdoc b/doc/syntax/modules_and_classes.rdoc index a82a6f27ed..dd70d4ac21 100644 --- a/doc/syntax/modules_and_classes.rdoc +++ b/doc/syntax/modules_and_classes.rdoc @@ -94,7 +94,7 @@ nesting: end However, if you use :: to define A::B without -nesting it inside +A+ a NameError exception will be raised because the nesting +nesting it inside +A+, a NameError exception will be raised because the nesting does not include +A+: module A @@ -129,7 +129,7 @@ method on a module is often called a "class method" instead of a "module method". See also Module#module_function which can convert an instance method into a class method.) -When a class method references a constant it uses the same rules as referencing +When a class method references a constant, it uses the same rules as referencing it outside the method as the scope is the same. Instance methods defined in a module are only callable when included. These @@ -342,4 +342,3 @@ is equivalent to this code block: end Both objects will have a +my_method+ that returns +2+. - diff --git a/doc/syntax/refinements.rdoc b/doc/syntax/refinements.rdoc index 968497ccb5..4cba61d396 100644 --- a/doc/syntax/refinements.rdoc +++ b/doc/syntax/refinements.rdoc @@ -260,4 +260,3 @@ This behavior may be changed in the future. See http://bugs.ruby-lang.org/projects/ruby-trunk/wiki/RefinementsSpec for the current specification for implementing refinements. The specification also contains more details. -