From 573762a7b7bbaf08aa1c27d95a9bcb15bac9ee2e Mon Sep 17 00:00:00 2001 From: zzak Date: Sun, 22 Dec 2013 20:13:09 +0000 Subject: * doc/syntax/methods.rdoc: [DOC] Added example for underscore conventions in method names. Also added doc to clarify encoding character set support for Ruby programs and elaborated on defining predicate and bang methods. Based on a patch by @gaurish [Fixes GH-477] https://github.com/ruby/ruby/pull/477 git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@44350 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- doc/syntax/methods.rdoc | 57 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 40 insertions(+), 17 deletions(-) (limited to 'doc/syntax/methods.rdoc') diff --git a/doc/syntax/methods.rdoc b/doc/syntax/methods.rdoc index 7fd69983f3..d7610f161d 100644 --- a/doc/syntax/methods.rdoc +++ b/doc/syntax/methods.rdoc @@ -8,8 +8,8 @@ definition: end A method definition consists of the +def+ keyword, a method name, the body of -the method, then the +end+ keyword. When called the method will execute the -body of the method. This method returns +2+. +the method, +return+ value and the +end+ keyword. When called the method will +execute the body of the method. This method returns +2+. This section only covers defining methods. See also the {syntax documentation on calling methods}[rdoc-ref:syntax/calling_methods.rdoc]. @@ -17,27 +17,50 @@ on calling methods}[rdoc-ref:syntax/calling_methods.rdoc]. == Method Names Method names may be one of the operators or must start a letter or a character -with the eight bit set. Typically method names are US-ASCII compatible since -the keys to type them exist on all keyboards. +with the eight bit set. It may contain letters, numbers, an _ +(underscore or low line) or a character with the eight bit set. The convention +is to use underscores to separate words in a multiword method name: -(Ruby programs must be written in a US-ASCII-compatible character set. In -such character sets if the eight bit is set it indicates an extended -character. Ruby allows method names and other identifiers to contain such -characters.) + def method_name + puts "use underscores to separate words" + end + +Ruby programs must be written in a US-ASCII-compatible character set such as +UTF-8, ISO-8859-1 etc. In such character sets if the eight bit is set it +indicates an extended character. Ruby allows method names and other identifiers +to contain such characters. Ruby programs cannot contain some characters like +ASCII NUL (\x00). + +The following are the examples of valid ruby methods: + + def hello + "hello" + end + + def こんにちは + puts "means hello in Japanese" + end -Method names may contain letters, numbers, an _ (underscore or -low line) or a character with the eight bit set. +Typically method names are US-ASCII compatible since the keys to type them +exist on all keyboards. Method names may end with a ! (bang or exclamation mark), a ? (question mark) or = equals sign. -In the ruby core library when a method ends with a bang it indicates there is -a non-bang method that has does not modify the receiver. This is typically -true for the standard library but does not hold true for other ruby libraries. - -Methods that end with a question mark do not always return just +true+ or -+false+. Often they will may return an object to indicate a true value (or -"truthy" value). +The bang methods(! at the end of method name) are called and +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 +counterpart(method name which does NOT end with !) of every bang +method (method name which does end with !) that has does not +modify the receiver. This convention is typically true for ruby core libary but +may/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 +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 -- cgit v1.2.3