From 6a45a690a2626fa4a8ccefaa8be3fc0a10076ba5 Mon Sep 17 00:00:00 2001 From: Waynn Lue Date: Wed, 8 Jan 2014 18:02:25 -0800 Subject: [PATCH 01/15] change to "check out" --- actionpack/RUNNING_UNIT_TESTS.rdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/actionpack/RUNNING_UNIT_TESTS.rdoc b/actionpack/RUNNING_UNIT_TESTS.rdoc index 08767ae133..3566821362 100644 --- a/actionpack/RUNNING_UNIT_TESTS.rdoc +++ b/actionpack/RUNNING_UNIT_TESTS.rdoc @@ -1,7 +1,7 @@ == Running with Rake The easiest way to run the unit tests is through Rake. The default task runs -the entire test suite for all classes. For more information, checkout the +the entire test suite for all classes. For more information, check out the full array of rake tasks with "rake -T" Rake can be found at http://rake.rubyforge.org From 4dbc62dabd9decbeed74f30f36062355e10def6b Mon Sep 17 00:00:00 2001 From: Waynn Lue Date: Mon, 13 Jan 2014 11:56:00 -0800 Subject: [PATCH 02/15] e-mail => email, and subject/verb agreement --- actionmailer/README.rdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/actionmailer/README.rdoc b/actionmailer/README.rdoc index c3dcd3c3e4..e425282fa8 100644 --- a/actionmailer/README.rdoc +++ b/actionmailer/README.rdoc @@ -74,7 +74,7 @@ Or you can just chain the methods together like: == Setting defaults -It is possible to set default values that will be used in every method in your Action Mailer class. To implement this functionality, you just call the public class method default which you get for free from ActionMailer::Base. This method accepts a Hash as the parameter. You can use any of the headers e-mail messages has, like :from as the key. You can also pass in a string as the key, like "Content-Type", but Action Mailer does this out of the box for you, so you won't need to worry about that. Finally, it is also possible to pass in a Proc that will get evaluated when it is needed. +It is possible to set default values that will be used in every method in your Action Mailer class. To implement this functionality, you just call the public class method default which you get for free from ActionMailer::Base. This method accepts a Hash as the parameter. You can use any of the headers email messages have, like :from as the key. You can also pass in a string as the key, like "Content-Type", but Action Mailer does this out of the box for you, so you won't need to worry about that. Finally, it is also possible to pass in a Proc that will get evaluated when it is needed. Note that every value you set with this method will get overwritten if you use the same key in your mailer method. From 6900b3e6ed05b48da360122595b59856f36601eb Mon Sep 17 00:00:00 2001 From: Waynn Lue Date: Mon, 13 Jan 2014 12:15:52 -0800 Subject: [PATCH 03/15] add punctuation --- actionpack/RUNNING_UNIT_TESTS.rdoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/actionpack/RUNNING_UNIT_TESTS.rdoc b/actionpack/RUNNING_UNIT_TESTS.rdoc index 3566821362..ad1448f61b 100644 --- a/actionpack/RUNNING_UNIT_TESTS.rdoc +++ b/actionpack/RUNNING_UNIT_TESTS.rdoc @@ -2,9 +2,9 @@ The easiest way to run the unit tests is through Rake. The default task runs the entire test suite for all classes. For more information, check out the -full array of rake tasks with "rake -T" +full array of rake tasks with "rake -T". -Rake can be found at http://rake.rubyforge.org +Rake can be found at http://rake.rubyforge.org. == Running by hand From 3d5c4a16472edadb158eb879bb5e7ef30403a93c Mon Sep 17 00:00:00 2001 From: Zachary Scott Date: Thu, 16 Jan 2014 11:06:10 -0800 Subject: [PATCH 04/15] Remove duplicate configuration option for ActiveSupport [ci skip] Fixes rails/rails#13732 --- guides/source/configuring.md | 1 - 1 file changed, 1 deletion(-) diff --git a/guides/source/configuring.md b/guides/source/configuring.md index c30b806907..78dc84180c 100644 --- a/guides/source/configuring.md +++ b/guides/source/configuring.md @@ -449,7 +449,6 @@ There are a few configuration options available in Active Support: * `ActiveSupport::Deprecation.silenced` sets whether or not to display deprecation warnings. -* `ActiveSupport::Logger.silencer` is set to `false` to disable the ability to silence logging in a block. The default is `true`. ### Configuring a Database From 1adaf6ca9fcaaa96cdb2438d6b95067f8f927ce3 Mon Sep 17 00:00:00 2001 From: Vipul A M Date: Fri, 24 Jan 2014 12:32:17 +0530 Subject: [PATCH 05/15] `requies` => `requires` --- guides/source/asset_pipeline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md index bce5d6c55f..b592442e9d 100644 --- a/guides/source/asset_pipeline.md +++ b/guides/source/asset_pipeline.md @@ -1145,7 +1145,7 @@ config.assets.digest = true ``` Rails 4 no longer sets default config values for Sprockets in `test.rb`, so -`test.rb` now requies Sprockets configuration. The old defaults in the test +`test.rb` now requires Sprockets configuration. The old defaults in the test environment are: `config.assets.compile = true`, `config.assets.compress = false`, `config.assets.debug = false` and `config.assets.digest = false`. From 5b31da48813cb37ca162b3ea7c224018b96f3033 Mon Sep 17 00:00:00 2001 From: Vipul A M Date: Fri, 24 Jan 2014 12:37:24 +0530 Subject: [PATCH 06/15] `easiy` => `easy` --- guides/source/configuring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/configuring.md b/guides/source/configuring.md index 78dc84180c..f6ad6d8f6b 100644 --- a/guides/source/configuring.md +++ b/guides/source/configuring.md @@ -580,7 +580,7 @@ Rails will now prepend "/app1" when generating links. #### Using Passenger -Passenger makes it easiy to run your application in a subdirectory. You can find +Passenger makes it easy to run your application in a subdirectory. You can find the relevant configuration in the [passenger manual](http://www.modrails.com/documentation/Users%20guide%20Apache.html#deploying_rails_to_sub_uri). From 3e28b7c2bbd278381e9cf89086c0d3ac62a58f72 Mon Sep 17 00:00:00 2001 From: Vipul A M Date: Fri, 24 Jan 2014 12:40:21 +0530 Subject: [PATCH 07/15] `framwork` => `framework` --- guides/source/testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/testing.md b/guides/source/testing.md index 165eca739a..b5119829b3 100644 --- a/guides/source/testing.md +++ b/guides/source/testing.md @@ -361,7 +361,7 @@ NOTE: The execution of each test method stops as soon as any error or an asserti When a test fails you are presented with the corresponding backtrace. By default Rails filters that backtrace and will only print lines relevant to your -application. This eliminates the framwork noise and helps to focus on your +application. This eliminates the framework noise and helps to focus on your code. However there are situations when you want to see the full backtrace. simply set the `BACKTRACE` environment variable to enable this behavior: From 9cc4dadb0b38ae1f686e16aebee97fc633fc6347 Mon Sep 17 00:00:00 2001 From: Vipul A M Date: Sat, 25 Jan 2014 14:04:09 +0530 Subject: [PATCH 08/15] Remove old comments about suppressing warnings. --- guides/source/contributing_to_ruby_on_rails.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md index 814237ba22..5ba6d8581c 100644 --- a/guides/source/contributing_to_ruby_on_rails.md +++ b/guides/source/contributing_to_ruby_on_rails.md @@ -136,7 +136,7 @@ You can invoke `test_jdbcmysql`, `test_jdbcsqlite3` or `test_jdbcpostgresql` als The test suite runs with warnings enabled. Ideally, Ruby on Rails should issue no warnings, but there may be a few, as well as some from third-party libraries. Please ignore (or fix!) them, if any, and submit patches that do not issue new warnings. -As of this writing (December, 2010) they are especially noisy with Ruby 1.9. If you are sure about what you are doing and would like to have a more clear output, there's a way to override the flag: +If you are sure about what you are doing and would like to have a more clear output, there's a way to override the flag: ```bash $ RUBYOPT=-W0 bundle exec rake test From 2fdbd599be4729fdc271a74557e8f45dec33c0f8 Mon Sep 17 00:00:00 2001 From: Calvin Tam Date: Fri, 7 Feb 2014 20:02:34 +1100 Subject: [PATCH 09/15] Fixed spelling error: `extracetd` => `extracted` --- guides/source/4_1_release_notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/4_1_release_notes.md b/guides/source/4_1_release_notes.md index 171572c77c..606a9cd5d1 100644 --- a/guides/source/4_1_release_notes.md +++ b/guides/source/4_1_release_notes.md @@ -566,7 +566,7 @@ for detailed changes. [More Details](upgrading_ruby_on_rails.html#changes-in-json-handling)) * Deprecated `ActiveSupport.encode_big_decimal_as_string` option. This feature has - been extracetd into the [activesupport-json_encoder](https://github.com/rails/activesupport-json_encoder) + been extracted into the [activesupport-json_encoder](https://github.com/rails/activesupport-json_encoder) gem. ([Pull Request](https://github.com/rails/rails/pull/13060) / [More Details](upgrading_ruby_on_rails.html#changes-in-json-handling)) From dbe3345c4f84f603b8a6d121229d1cc9f5d3be8c Mon Sep 17 00:00:00 2001 From: Zachary Scott Date: Sun, 9 Feb 2014 03:06:19 +0200 Subject: [PATCH 10/15] Fix grammar of internal comment and modify it's location --- .../lib/active_support/core_ext/module/attr_internal.rb | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/activesupport/lib/active_support/core_ext/module/attr_internal.rb b/activesupport/lib/active_support/core_ext/module/attr_internal.rb index db07d549b0..67f0e0335d 100644 --- a/activesupport/lib/active_support/core_ext/module/attr_internal.rb +++ b/activesupport/lib/active_support/core_ext/module/attr_internal.rb @@ -27,7 +27,8 @@ class Module def attr_internal_define(attr_name, type) internal_name = attr_internal_ivar_name(attr_name).sub(/\A@/, '') - class_eval do # class_eval is necessary on 1.9 or else the methods a made private + # class_eval is necessary on 1.9 or else the methods are made private + class_eval do # use native attr_* methods as they are faster on some Ruby implementations send("attr_#{type}", internal_name) end From 17b0edde5782c424dbae6020e09a51831e8de7f9 Mon Sep 17 00:00:00 2001 From: Zachary Scott Date: Sun, 9 Feb 2014 03:07:33 +0200 Subject: [PATCH 11/15] Specify what #starts_with? we're talking about. Also added a note what kind of exception we should expect for this internal comment. --- activesupport/lib/active_support/dependencies.rb | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/activesupport/lib/active_support/dependencies.rb b/activesupport/lib/active_support/dependencies.rb index 6be19771f5..b519ef9f71 100644 --- a/activesupport/lib/active_support/dependencies.rb +++ b/activesupport/lib/active_support/dependencies.rb @@ -407,7 +407,8 @@ module ActiveSupport #:nodoc: end def load_once_path?(path) - # to_s works around a ruby1.9 issue where #starts_with?(Pathname) will always return false + # to_s works around a ruby1.9 issue where String#starts_with?(Pathname) + # will raise a TypeError: no implicit conversion of Pathname into String autoload_once_paths.any? { |base| path.starts_with? base.to_s } end From 4e4a92e78a29d2508702336a440cb0d14cbf1f39 Mon Sep 17 00:00:00 2001 From: Yves Senn Date: Tue, 4 Feb 2014 13:37:11 +0100 Subject: [PATCH 12/15] docs, link MySQL manual for multi column indexes. [ci ckip]. Closes #9131. --- guides/source/active_record_validations.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/guides/source/active_record_validations.md b/guides/source/active_record_validations.md index efa826e8df..b0bd16791d 100644 --- a/guides/source/active_record_validations.md +++ b/guides/source/active_record_validations.md @@ -575,7 +575,9 @@ This helper validates that the attribute's value is unique right before the object gets saved. It does not create a uniqueness constraint in the database, so it may happen that two different database connections create two records with the same value for a column that you intend to be unique. To avoid that, -you must create a unique index in your database. +you must create a unique index on both columns in your database. See +[the MySQL manual](http://dev.mysql.com/doc/refman/5.6/en/multiple-column-indexes.html) +for more details about multi column indexes. ```ruby class Account < ActiveRecord::Base From 605c81b9de24535993046d9a50408ad98feee9c0 Mon Sep 17 00:00:00 2001 From: Zachary Scott Date: Sun, 9 Feb 2014 09:39:22 +0200 Subject: [PATCH 13/15] Use full-length version of multiple from c7abc51 --- guides/source/active_record_validations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/active_record_validations.md b/guides/source/active_record_validations.md index b0bd16791d..990c820868 100644 --- a/guides/source/active_record_validations.md +++ b/guides/source/active_record_validations.md @@ -577,7 +577,7 @@ so it may happen that two different database connections create two records with the same value for a column that you intend to be unique. To avoid that, you must create a unique index on both columns in your database. See [the MySQL manual](http://dev.mysql.com/doc/refman/5.6/en/multiple-column-indexes.html) -for more details about multi column indexes. +for more details about multiple column indexes. ```ruby class Account < ActiveRecord::Base From 7afd92e60b38b34404a38592d6e3e652c1623b6a Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sun, 26 Jan 2014 22:10:05 +0100 Subject: [PATCH 14/15] adds a section about booleans in the API guidelines [ci skip] --- guides/source/api_documentation_guidelines.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/guides/source/api_documentation_guidelines.md b/guides/source/api_documentation_guidelines.md index 311cc23cf0..622d57a943 100644 --- a/guides/source/api_documentation_guidelines.md +++ b/guides/source/api_documentation_guidelines.md @@ -128,6 +128,53 @@ On the other hand, regular comments do not use an arrow: # polymorphic_url(record) # same as comment_url(record) ``` +Booleans +-------- + +In predicates and flags prefer documenting boolean semantics over exact values. + +When "true" or "false" are used as defined in Ruby use regular font. The +singletons `true` and `false` need fixed-width font. Please avoid terms like +"truthy", Ruby defines what is true and false in the language, and thus those +words have a technical meaning and need no substitutes. + +As a rule of thumb, do not document singletons unless absolutely necessary. That +prevents artificial constructs like `!!` or ternaries, allows refactors, and the +code does not need to rely on the exact values returned by methods being called +in the implementation. + +For example: + +```markdown +`config.action_mailer.perform_deliveries` specifies whether mail will actually be delivered and is true by default +``` + +the user does not need to know which is the actual default value of the flag, +and so we only document its boolean semantics. + +An example with a predicate: + +```ruby +# Returns true if the collection is empty. +# +# If the collection has been loaded +# it is equivalent to collection.size.zero?. If the +# collection has not been loaded, it is equivalent to +# collection.exists?. If the collection has not already been +# loaded and you are going to fetch the records anyway it is better to +# check collection.length.zero?. +def empty? + if loaded? + size.zero? + else + @target.blank? && !scope.exists? + end +end +``` + +The API is careful not to commit to any particular value, the predicate has +predicate semantics, that's enough. + Filenames --------- From ae7580ac287df477e7f5dd57136d5eec3813629d Mon Sep 17 00:00:00 2001 From: Zachary Scott Date: Sun, 9 Feb 2014 10:03:30 +0200 Subject: [PATCH 15/15] Fixed a grammatical error in Booleans section of API documentation guide from e1e17a5 --- guides/source/api_documentation_guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/api_documentation_guidelines.md b/guides/source/api_documentation_guidelines.md index 622d57a943..26afa72b8d 100644 --- a/guides/source/api_documentation_guidelines.md +++ b/guides/source/api_documentation_guidelines.md @@ -172,7 +172,7 @@ def empty? end ``` -The API is careful not to commit to any particular value, the predicate has +The API is careful not to commit to any particular value, the method has predicate semantics, that's enough. Filenames