rails 4.1.16 → 4.2.0.beta1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (141) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +3 -3
  3. data/guides/CHANGELOG.md +13 -102
  4. data/guides/Rakefile +2 -2
  5. data/guides/assets/javascripts/guides.js +6 -0
  6. data/guides/assets/stylesheets/main.css +4 -1
  7. data/guides/bug_report_templates/action_controller_gem.rb +2 -2
  8. data/guides/bug_report_templates/action_controller_master.rb +5 -2
  9. data/guides/bug_report_templates/active_record_master.rb +2 -0
  10. data/guides/rails_guides.rb +2 -2
  11. data/guides/rails_guides/helpers.rb +1 -1
  12. data/guides/rails_guides/levenshtein.rb +29 -21
  13. data/guides/rails_guides/markdown.rb +6 -7
  14. data/guides/rails_guides/markdown/renderer.rb +1 -1
  15. data/guides/source/2_3_release_notes.md +3 -3
  16. data/guides/source/3_0_release_notes.md +4 -4
  17. data/guides/source/3_1_release_notes.md +2 -2
  18. data/guides/source/3_2_release_notes.md +2 -2
  19. data/guides/source/4_1_release_notes.md +8 -9
  20. data/guides/source/4_2_release_notes.md +572 -0
  21. data/guides/source/_license.html.erb +1 -1
  22. data/guides/source/_welcome.html.erb +2 -8
  23. data/guides/source/action_controller_overview.md +79 -7
  24. data/guides/source/action_mailer_basics.md +36 -11
  25. data/guides/source/action_view_overview.md +138 -119
  26. data/guides/source/active_job_basics.md +253 -0
  27. data/guides/source/active_model_basics.md +23 -0
  28. data/guides/source/active_record_basics.md +16 -15
  29. data/guides/source/active_record_callbacks.md +12 -9
  30. data/guides/source/{migrations.md → active_record_migrations.md} +90 -217
  31. data/guides/source/active_record_postgresql.md +437 -0
  32. data/guides/source/active_record_querying.md +261 -261
  33. data/guides/source/active_record_validations.md +7 -7
  34. data/guides/source/active_support_core_extensions.md +105 -44
  35. data/guides/source/active_support_instrumentation.md +3 -2
  36. data/guides/source/api_documentation_guidelines.md +62 -16
  37. data/guides/source/asset_pipeline.md +58 -46
  38. data/guides/source/association_basics.md +47 -38
  39. data/guides/source/caching_with_rails.md +31 -6
  40. data/guides/source/command_line.md +56 -25
  41. data/guides/source/configuring.md +98 -19
  42. data/guides/source/contributing_to_ruby_on_rails.md +174 -111
  43. data/guides/source/credits.html.erb +1 -1
  44. data/guides/source/debugging_rails_applications.md +438 -284
  45. data/guides/source/development_dependencies_install.md +17 -4
  46. data/guides/source/documents.yaml +11 -7
  47. data/guides/source/engines.md +192 -203
  48. data/guides/source/form_helpers.md +54 -45
  49. data/guides/source/generators.md +20 -11
  50. data/guides/source/getting_started.md +330 -191
  51. data/guides/source/i18n.md +92 -62
  52. data/guides/source/index.html.erb +1 -0
  53. data/guides/source/initialization.md +108 -59
  54. data/guides/source/layout.html.erb +1 -4
  55. data/guides/source/layouts_and_rendering.md +24 -23
  56. data/guides/source/nested_model_forms.md +3 -3
  57. data/guides/source/plugins.md +26 -26
  58. data/guides/source/rails_application_templates.md +21 -3
  59. data/guides/source/rails_on_rack.md +1 -1
  60. data/guides/source/routing.md +97 -71
  61. data/guides/source/ruby_on_rails_guides_guidelines.md +10 -12
  62. data/guides/source/security.md +39 -33
  63. data/guides/source/testing.md +111 -108
  64. data/guides/source/upgrading_ruby_on_rails.md +131 -14
  65. data/guides/source/working_with_javascript_in_rails.md +18 -16
  66. data/guides/w3c_validator.rb +2 -0
  67. metadata +37 -94
  68. data/guides/bug_report_templates/generic_gem.rb +0 -15
  69. data/guides/bug_report_templates/generic_master.rb +0 -26
  70. data/guides/code/getting_started/Gemfile +0 -40
  71. data/guides/code/getting_started/Gemfile.lock +0 -125
  72. data/guides/code/getting_started/README.rdoc +0 -28
  73. data/guides/code/getting_started/Rakefile +0 -6
  74. data/guides/code/getting_started/app/assets/javascripts/application.js +0 -15
  75. data/guides/code/getting_started/app/assets/javascripts/comments.js.coffee +0 -3
  76. data/guides/code/getting_started/app/assets/javascripts/posts.js.coffee +0 -3
  77. data/guides/code/getting_started/app/assets/javascripts/welcome.js.coffee +0 -3
  78. data/guides/code/getting_started/app/assets/stylesheets/application.css +0 -13
  79. data/guides/code/getting_started/app/assets/stylesheets/comments.css.scss +0 -3
  80. data/guides/code/getting_started/app/assets/stylesheets/posts.css.scss +0 -3
  81. data/guides/code/getting_started/app/assets/stylesheets/welcome.css.scss +0 -3
  82. data/guides/code/getting_started/app/controllers/application_controller.rb +0 -5
  83. data/guides/code/getting_started/app/controllers/comments_controller.rb +0 -23
  84. data/guides/code/getting_started/app/controllers/posts_controller.rb +0 -53
  85. data/guides/code/getting_started/app/controllers/welcome_controller.rb +0 -4
  86. data/guides/code/getting_started/app/helpers/application_helper.rb +0 -2
  87. data/guides/code/getting_started/app/helpers/comments_helper.rb +0 -2
  88. data/guides/code/getting_started/app/helpers/posts_helper.rb +0 -2
  89. data/guides/code/getting_started/app/helpers/welcome_helper.rb +0 -2
  90. data/guides/code/getting_started/app/models/comment.rb +0 -3
  91. data/guides/code/getting_started/app/models/post.rb +0 -7
  92. data/guides/code/getting_started/app/views/comments/_comment.html.erb +0 -15
  93. data/guides/code/getting_started/app/views/comments/_form.html.erb +0 -13
  94. data/guides/code/getting_started/app/views/layouts/application.html.erb +0 -14
  95. data/guides/code/getting_started/app/views/posts/_form.html.erb +0 -27
  96. data/guides/code/getting_started/app/views/posts/edit.html.erb +0 -5
  97. data/guides/code/getting_started/app/views/posts/index.html.erb +0 -21
  98. data/guides/code/getting_started/app/views/posts/new.html.erb +0 -5
  99. data/guides/code/getting_started/app/views/posts/show.html.erb +0 -18
  100. data/guides/code/getting_started/app/views/welcome/index.html.erb +0 -4
  101. data/guides/code/getting_started/bin/bundle +0 -4
  102. data/guides/code/getting_started/bin/rails +0 -4
  103. data/guides/code/getting_started/bin/rake +0 -4
  104. data/guides/code/getting_started/config.ru +0 -4
  105. data/guides/code/getting_started/config/application.rb +0 -18
  106. data/guides/code/getting_started/config/boot.rb +0 -4
  107. data/guides/code/getting_started/config/database.yml +0 -25
  108. data/guides/code/getting_started/config/environment.rb +0 -5
  109. data/guides/code/getting_started/config/environments/development.rb +0 -30
  110. data/guides/code/getting_started/config/environments/production.rb +0 -80
  111. data/guides/code/getting_started/config/environments/test.rb +0 -36
  112. data/guides/code/getting_started/config/initializers/backtrace_silencers.rb +0 -7
  113. data/guides/code/getting_started/config/initializers/filter_parameter_logging.rb +0 -4
  114. data/guides/code/getting_started/config/initializers/inflections.rb +0 -16
  115. data/guides/code/getting_started/config/initializers/locale.rb +0 -9
  116. data/guides/code/getting_started/config/initializers/mime_types.rb +0 -5
  117. data/guides/code/getting_started/config/initializers/secret_token.rb +0 -12
  118. data/guides/code/getting_started/config/initializers/session_store.rb +0 -3
  119. data/guides/code/getting_started/config/initializers/wrap_parameters.rb +0 -14
  120. data/guides/code/getting_started/config/locales/en.yml +0 -23
  121. data/guides/code/getting_started/config/routes.rb +0 -7
  122. data/guides/code/getting_started/db/migrate/20130122042648_create_posts.rb +0 -10
  123. data/guides/code/getting_started/db/migrate/20130122045842_create_comments.rb +0 -11
  124. data/guides/code/getting_started/db/schema.rb +0 -33
  125. data/guides/code/getting_started/db/seeds.rb +0 -7
  126. data/guides/code/getting_started/public/404.html +0 -60
  127. data/guides/code/getting_started/public/422.html +0 -60
  128. data/guides/code/getting_started/public/500.html +0 -59
  129. data/guides/code/getting_started/public/favicon.ico +0 -0
  130. data/guides/code/getting_started/public/robots.txt +0 -5
  131. data/guides/code/getting_started/test/controllers/comments_controller_test.rb +0 -7
  132. data/guides/code/getting_started/test/controllers/posts_controller_test.rb +0 -7
  133. data/guides/code/getting_started/test/controllers/welcome_controller_test.rb +0 -9
  134. data/guides/code/getting_started/test/fixtures/comments.yml +0 -11
  135. data/guides/code/getting_started/test/fixtures/posts.yml +0 -9
  136. data/guides/code/getting_started/test/helpers/comments_helper_test.rb +0 -4
  137. data/guides/code/getting_started/test/helpers/posts_helper_test.rb +0 -4
  138. data/guides/code/getting_started/test/helpers/welcome_helper_test.rb +0 -4
  139. data/guides/code/getting_started/test/models/comment_test.rb +0 -7
  140. data/guides/code/getting_started/test/models/post_test.rb +0 -7
  141. data/guides/code/getting_started/test/test_helper.rb +0 -12
@@ -910,8 +910,8 @@ end
910
910
  The easiest way to add custom validators for validating individual attributes
911
911
  is with the convenient `ActiveModel::EachValidator`. In this case, the custom
912
912
  validator class must implement a `validate_each` method which takes three
913
- arguments: record, attribute and value which correspond to the instance, the
914
- attribute to be validated and the value of the attribute in the passed
913
+ arguments: record, attribute, and value. These correspond to the instance, the
914
+ attribute to be validated, and the value of the attribute in the passed
915
915
  instance.
916
916
 
917
917
  ```ruby
@@ -1129,15 +1129,15 @@ generating a scaffold, Rails will put some ERB into the `_form.html.erb` that
1129
1129
  it generates that displays the full list of errors on that model.
1130
1130
 
1131
1131
  Assuming we have a model that's been saved in an instance variable named
1132
- `@post`, it looks like this:
1132
+ `@article`, it looks like this:
1133
1133
 
1134
1134
  ```ruby
1135
- <% if @post.errors.any? %>
1135
+ <% if @article.errors.any? %>
1136
1136
  <div id="error_explanation">
1137
- <h2><%= pluralize(@post.errors.count, "error") %> prohibited this post from being saved:</h2>
1137
+ <h2><%= pluralize(@article.errors.count, "error") %> prohibited this article from being saved:</h2>
1138
1138
 
1139
1139
  <ul>
1140
- <% @post.errors.full_messages.each do |msg| %>
1140
+ <% @article.errors.full_messages.each do |msg| %>
1141
1141
  <li><%= msg %></li>
1142
1142
  <% end %>
1143
1143
  </ul>
@@ -1151,7 +1151,7 @@ the entry.
1151
1151
 
1152
1152
  ```
1153
1153
  <div class="field_with_errors">
1154
- <input id="post_title" name="post[title]" size="30" type="text" value="">
1154
+ <input id="article_title" name="article[title]" size="30" type="text" value="">
1155
1155
  </div>
1156
1156
  ```
1157
1157
 
@@ -157,9 +157,9 @@ Active Support provides `duplicable?` to programmatically query an object about
157
157
 
158
158
  ```ruby
159
159
  "foo".duplicable? # => true
160
- "".duplicable? # => true
160
+ "".duplicable? # => true
161
161
  0.0.duplicable? # => false
162
- false.duplicable? # => false
162
+ false.duplicable? # => false
163
163
  ```
164
164
 
165
165
  By definition all objects are `duplicable?` except `nil`, `false`, `true`, symbols, numbers, class, and module objects.
@@ -572,12 +572,12 @@ NOTE: Defined in `active_support/core_ext/module/aliasing.rb`.
572
572
 
573
573
  #### `alias_attribute`
574
574
 
575
- Model attributes have a reader, a writer, and a predicate. You can alias a model attribute having the corresponding three methods defined for you in one shot. As in other aliasing methods, the new name is the first argument, and the old name is the second (my mnemonic is they go in the same order as if you did an assignment):
575
+ Model attributes have a reader, a writer, and a predicate. You can alias a model attribute having the corresponding three methods defined for you in one shot. As in other aliasing methods, the new name is the first argument, and the old name is the second (one mnemonic is that they go in the same order as if you did an assignment):
576
576
 
577
577
  ```ruby
578
578
  class User < ActiveRecord::Base
579
- # let me refer to the email column as "login",
580
- # possibly meaningful for authentication code
579
+ # You can refer to the email column as "login".
580
+ # This can be meaningful for authentication code.
581
581
  alias_attribute :login, :email
582
582
  end
583
583
  ```
@@ -761,7 +761,7 @@ Arguments may be bare constant names:
761
761
  Math.qualified_const_get("E") # => 2.718281828459045
762
762
  ```
763
763
 
764
- These methods are analogous to their builtin counterparts. In particular,
764
+ These methods are analogous to their built-in counterparts. In particular,
765
765
  `qualified_constant_defined?` accepts an optional second argument to be
766
766
  able to say whether you want the predicate to look in the ancestors.
767
767
  This flag is taken into account for each constant in the expression while
@@ -792,7 +792,7 @@ N.qualified_const_defined?("C::X") # => true
792
792
  As the last example implies, the second argument defaults to true,
793
793
  as in `const_defined?`.
794
794
 
795
- For coherence with the builtin methods only relative paths are accepted.
795
+ For coherence with the built-in methods only relative paths are accepted.
796
796
  Absolute qualified constant names like `::Math::PI` raise `NameError`.
797
797
 
798
798
  NOTE: Defined in `active_support/core_ext/module/qualified_const.rb`.
@@ -964,20 +964,7 @@ NOTE: Defined in `active_support/core_ext/module/delegation.rb`
964
964
 
965
965
  There are cases where you need to define a method with `define_method`, but don't know whether a method with that name already exists. If it does, a warning is issued if they are enabled. No big deal, but not clean either.
966
966
 
967
- The method `redefine_method` prevents such a potential warning, removing the existing method before if needed. Rails uses it in a few places, for instance when it generates an association's API:
968
-
969
- ```ruby
970
- redefine_method("#{reflection.name}=") do |new_value|
971
- association = association_instance_get(reflection.name)
972
-
973
- if association.nil? || association.target != new_value
974
- association = association_proxy_class.new(self, reflection)
975
- end
976
-
977
- association.replace(new_value)
978
- association_instance_set(reflection.name, new_value.nil? ? nil : association)
979
- end
980
- ```
967
+ The method `redefine_method` prevents such a potential warning, removing the existing method before if needed.
981
968
 
982
969
  NOTE: Defined in `active_support/core_ext/module/remove_method.rb`
983
970
 
@@ -1178,9 +1165,9 @@ Inserting data into HTML templates needs extra care. For example, you can't just
1178
1165
 
1179
1166
  #### Safe Strings
1180
1167
 
1181
- Active Support has the concept of <i>(html) safe</i> strings. A safe string is one that is marked as being insertable into HTML as is. It is trusted, no matter whether it has been escaped or not.
1168
+ Active Support has the concept of _(html) safe_ strings. A safe string is one that is marked as being insertable into HTML as is. It is trusted, no matter whether it has been escaped or not.
1182
1169
 
1183
- Strings are considered to be <i>unsafe</i> by default:
1170
+ Strings are considered to be _unsafe_ by default:
1184
1171
 
1185
1172
  ```ruby
1186
1173
  "".html_safe? # => false
@@ -1281,7 +1268,7 @@ The method `squish` strips leading and trailing whitespace, and substitutes runs
1281
1268
 
1282
1269
  There's also the destructive version `String#squish!`.
1283
1270
 
1284
- Note that it handles both ASCII and Unicode whitespace.
1271
+ Note that it handles both ASCII and Unicode whitespace like mongolian vowel separator (U+180E).
1285
1272
 
1286
1273
  NOTE: Defined in `active_support/core_ext/string/filters.rb`.
1287
1274
 
@@ -1644,6 +1631,9 @@ Given a string with a qualified constant name, `demodulize` returns the very con
1644
1631
  "Product".demodulize # => "Product"
1645
1632
  "Backoffice::UsersController".demodulize # => "UsersController"
1646
1633
  "Admin::Hotel::ReservationUtils".demodulize # => "ReservationUtils"
1634
+ "::Inflections".demodulize # => "Inflections"
1635
+ "".demodulize # => ""
1636
+
1647
1637
  ```
1648
1638
 
1649
1639
  Active Record for example uses this method to compute the name of a counter cache column:
@@ -1778,21 +1768,36 @@ NOTE: Defined in `active_support/core_ext/string/inflections.rb`.
1778
1768
 
1779
1769
  #### `humanize`
1780
1770
 
1781
- The method `humanize` gives you a sensible name for display out of an attribute name. To do so it replaces underscores with spaces, removes any "_id" suffix, and capitalizes the first word:
1771
+ The method `humanize` tweaks an attribute name for display to end users.
1772
+
1773
+ Specifically performs these transformations:
1774
+
1775
+ * Applies human inflection rules to the argument.
1776
+ * Deletes leading underscores, if any.
1777
+ * Removes a "_id" suffix if present.
1778
+ * Replaces underscores with spaces, if any.
1779
+ * Downcases all words except acronyms.
1780
+ * Capitalizes the first word.
1781
+
1782
+ The capitalization of the first word can be turned off by setting the
1783
+ +:capitalize+ option to false (default is true).
1782
1784
 
1783
1785
  ```ruby
1784
- "name".humanize # => "Name"
1785
- "author_id".humanize # => "Author"
1786
- "comments_count".humanize # => "Comments count"
1786
+ "name".humanize # => "Name"
1787
+ "author_id".humanize # => "Author"
1788
+ "author_id".humanize(capitalize: false) # => "author"
1789
+ "comments_count".humanize # => "Comments count"
1790
+ "_id".humanize # => "Id"
1787
1791
  ```
1788
1792
 
1789
- The capitalization of the first word can be turned off by setting the optional parameter `capitalize` to false:
1793
+ If "SSL" was defined to be an acronym:
1790
1794
 
1791
1795
  ```ruby
1792
- "author_id".humanize(capitalize: false) # => "author"
1796
+ 'ssl_error'.humanize # => "SSL error"
1793
1797
  ```
1794
1798
 
1795
- The helper method `full_messages` uses `humanize` as a fallback to include attribute names:
1799
+ The helper method `full_messages` uses `humanize` as a fallback to include
1800
+ attribute names:
1796
1801
 
1797
1802
  ```ruby
1798
1803
  def full_messages
@@ -2719,11 +2724,14 @@ The method `transform_keys` accepts a block and returns a hash that has applied
2719
2724
  # => {"" => nil, "A" => :a, "1" => 1}
2720
2725
  ```
2721
2726
 
2722
- The result in case of collision is undefined:
2727
+ In case of key collision, one of the values will be chosen. The chosen value may not always be the same given the same hash:
2723
2728
 
2724
2729
  ```ruby
2725
2730
  {"a" => 1, a: 2}.transform_keys { |key| key.to_s.upcase }
2726
- # => {"A" => 2}, in my test, can't rely on this result though
2731
+ # The result could either be
2732
+ # => {"A"=>2}
2733
+ # or
2734
+ # => {"A"=>1}
2727
2735
  ```
2728
2736
 
2729
2737
  This method may be useful for example to build specialized conversions. For instance `stringify_keys` and `symbolize_keys` use `transform_keys` to perform their key conversions:
@@ -2758,11 +2766,14 @@ The method `stringify_keys` returns a hash that has a stringified version of the
2758
2766
  # => {"" => nil, "a" => :a, "1" => 1}
2759
2767
  ```
2760
2768
 
2761
- The result in case of collision is undefined:
2769
+ In case of key collision, one of the values will be chosen. The chosen value may not always be the same given the same hash:
2762
2770
 
2763
2771
  ```ruby
2764
2772
  {"a" => 1, a: 2}.stringify_keys
2765
- # => {"a" => 2}, in my test, can't rely on this result though
2773
+ # The result could either be
2774
+ # => {"a"=>2}
2775
+ # or
2776
+ # => {"a"=>1}
2766
2777
  ```
2767
2778
 
2768
2779
  This method may be useful for example to easily accept both symbols and strings as options. For instance `ActionView::Helpers::FormHelper` defines:
@@ -2799,11 +2810,14 @@ The method `symbolize_keys` returns a hash that has a symbolized version of the
2799
2810
 
2800
2811
  WARNING. Note in the previous example only one key was symbolized.
2801
2812
 
2802
- The result in case of collision is undefined:
2813
+ In case of key collision, one of the values will be chosen. The chosen value may not always be the same given the same hash:
2803
2814
 
2804
2815
  ```ruby
2805
2816
  {"a" => 1, a: 2}.symbolize_keys
2806
- # => {:a=>2}, in my test, can't rely on this result though
2817
+ # The result could either be
2818
+ # => {:a=>2}
2819
+ # or
2820
+ # => {:a=>1}
2807
2821
  ```
2808
2822
 
2809
2823
  This method may be useful for example to easily accept both symbols and strings as options. For instance `ActionController::UrlRewriter` defines
@@ -2911,7 +2925,7 @@ NOTE: Defined in `active_support/core_ext/hash/indifferent_access.rb`.
2911
2925
 
2912
2926
  ### Compacting
2913
2927
 
2914
- The methods `compact` and `compact!` return a Hash without items with `nil` value.
2928
+ The methods `compact` and `compact!` return a Hash without items with `nil` value.
2915
2929
 
2916
2930
  ```ruby
2917
2931
  {a: 1, b: 2, c: nil}.compact # => {a: 1, b: 2}
@@ -3003,6 +3017,53 @@ The method `Range#overlaps?` says whether any two given ranges have non-void int
3003
3017
 
3004
3018
  NOTE: Defined in `active_support/core_ext/range/overlaps.rb`.
3005
3019
 
3020
+ Extensions to `Proc`
3021
+ --------------------
3022
+
3023
+ ### `bind`
3024
+
3025
+ As you surely know Ruby has an `UnboundMethod` class whose instances are methods that belong to the limbo of methods without a self. The method `Module#instance_method` returns an unbound method for example:
3026
+
3027
+ ```ruby
3028
+ Hash.instance_method(:delete) # => #<UnboundMethod: Hash#delete>
3029
+ ```
3030
+
3031
+ An unbound method is not callable as is, you need to bind it first to an object with `bind`:
3032
+
3033
+ ```ruby
3034
+ clear = Hash.instance_method(:clear)
3035
+ clear.bind({a: 1}).call # => {}
3036
+ ```
3037
+
3038
+ Active Support defines `Proc#bind` with an analogous purpose:
3039
+
3040
+ ```ruby
3041
+ Proc.new { size }.bind([]).call # => 0
3042
+ ```
3043
+
3044
+ As you see that's callable and bound to the argument, the return value is indeed a `Method`.
3045
+
3046
+ NOTE: To do so `Proc#bind` actually creates a method under the hood. If you ever see a method with a weird name like `__bind_1256598120_237302` in a stack trace you know now where it comes from.
3047
+
3048
+ Action Pack uses this trick in `rescue_from` for example, which accepts the name of a method and also a proc as callbacks for a given rescued exception. It has to call them in either case, so a bound method is returned by `handler_for_rescue`, thus simplifying the code in the caller:
3049
+
3050
+ ```ruby
3051
+ def handler_for_rescue(exception)
3052
+ _, rescuer = Array(rescue_handlers).reverse.detect do |klass_name, handler|
3053
+ ...
3054
+ end
3055
+
3056
+ case rescuer
3057
+ when Symbol
3058
+ method(rescuer)
3059
+ when Proc
3060
+ rescuer.bind(self)
3061
+ end
3062
+ end
3063
+ ```
3064
+
3065
+ NOTE: Defined in `active_support/core_ext/proc.rb`.
3066
+
3006
3067
  Extensions to `Date`
3007
3068
  --------------------
3008
3069
 
@@ -3611,9 +3672,9 @@ t.advance(seconds: 1)
3611
3672
 
3612
3673
  #### `Time.current`
3613
3674
 
3614
- Active Support defines `Time.current` to be today in the current time zone. That's like `Time.now`, except that it honors the user time zone, if defined. It also defines `Time.yesterday` and `Time.tomorrow`, and the instance predicates `past?`, `today?`, and `future?`, all of them relative to `Time.current`.
3675
+ Active Support defines `Time.current` to be today in the current time zone. That's like `Time.now`, except that it honors the user time zone, if defined. It also defines the instance predicates `past?`, `today?`, and `future?`, all of them relative to `Time.current`.
3615
3676
 
3616
- When making Time comparisons using methods which honor the user time zone, make sure to use `Time.current` and not `Time.now`. There are cases where the user time zone might be in the future compared to the system time zone, which `Time.today` uses by default. This means `Time.now` may equal `Time.yesterday`.
3677
+ When making Time comparisons using methods which honor the user time zone, make sure to use `Time.current` instead of `Time.now`. There are cases where the user time zone might be in the future compared to the system time zone, which `Time.now` uses by default. This means `Time.now.to_date` may equal `Date.yesterday`.
3617
3678
 
3618
3679
  #### `all_day`, `all_week`, `all_month`, `all_quarter` and `all_year`
3619
3680
 
@@ -3777,7 +3838,7 @@ The name may be given as a symbol or string. A symbol is tested against the bare
3777
3838
 
3778
3839
  TIP: A symbol can represent a fully-qualified constant name as in `:"ActiveRecord::Base"`, so the behavior for symbols is defined for convenience, not because it has to be that way technically.
3779
3840
 
3780
- For example, when an action of `PostsController` is called Rails tries optimistically to use `PostsHelper`. It is OK that the helper module does not exist, so if an exception for that constant name is raised it should be silenced. But it could be the case that `posts_helper.rb` raises a `NameError` due to an actual unknown constant. That should be reraised. The method `missing_name?` provides a way to distinguish both cases:
3841
+ For example, when an action of `ArticlesController` is called Rails tries optimistically to use `ArticlesHelper`. It is OK that the helper module does not exist, so if an exception for that constant name is raised it should be silenced. But it could be the case that `articles_helper.rb` raises a `NameError` due to an actual unknown constant. That should be reraised. The method `missing_name?` provides a way to distinguish both cases:
3781
3842
 
3782
3843
  ```ruby
3783
3844
  def default_helper_module!
@@ -3791,7 +3852,7 @@ rescue NameError => e
3791
3852
  end
3792
3853
  ```
3793
3854
 
3794
- NOTE: Defined in `actionpack/lib/abstract_controller/helpers.rb`.
3855
+ NOTE: Defined in `active_support/core_ext/name_error.rb`.
3795
3856
 
3796
3857
  Extensions to `LoadError`
3797
3858
  -------------------------
@@ -3800,7 +3861,7 @@ Active Support adds `is_missing?` to `LoadError`, and also assigns that class to
3800
3861
 
3801
3862
  Given a path name `is_missing?` tests whether the exception was raised due to that particular file (except perhaps for the ".rb" extension).
3802
3863
 
3803
- For example, when an action of `PostsController` is called Rails tries to load `posts_helper.rb`, but that file may not exist. That's fine, the helper module is not mandatory so Rails silences a load error. But it could be the case that the helper module does exist and in turn requires another library that is missing. In that case Rails must reraise the exception. The method `is_missing?` provides a way to distinguish both cases:
3864
+ For example, when an action of `ArticlesController` is called Rails tries to load `articles_helper.rb`, but that file may not exist. That's fine, the helper module is not mandatory so Rails silences a load error. But it could be the case that the helper module does exist and in turn requires another library that is missing. In that case Rails must reraise the exception. The method `is_missing?` provides a way to distinguish both cases:
3804
3865
 
3805
3866
  ```ruby
3806
3867
  def default_helper_module!
@@ -3814,4 +3875,4 @@ rescue NameError => e
3814
3875
  end
3815
3876
  ```
3816
3877
 
3817
- NOTE: Defined in `actionpack/lib/abstract_controller/helpers.rb`.
3878
+ NOTE: Defined in `active_support/core_ext/load_error.rb`.
@@ -17,7 +17,7 @@ After reading this guide, you will know:
17
17
  Introduction to instrumentation
18
18
  -------------------------------
19
19
 
20
- The instrumentation API provided by Active Support allows developers to provide hooks which other developers may hook into. There are several of these within the Rails framework, as described below in <TODO: link to section detailing each hook point>. With this API, developers can choose to be notified when certain events occur inside their application or another piece of Ruby code.
20
+ The instrumentation API provided by Active Support allows developers to provide hooks which other developers may hook into. There are several of these within the Rails framework, as described below in (TODO: link to section detailing each hook point). With this API, developers can choose to be notified when certain events occur inside their application or another piece of Ruby code.
21
21
 
22
22
  For example, there is a hook provided within Active Record that is called every time Active Record uses an SQL query on a database. This hook could be **subscribed** to, and used to track the number of queries during a certain action. There's another hook around the processing of an action of a controller. This could be used, for instance, to track how long a specific action has taken.
23
23
 
@@ -364,7 +364,7 @@ INFO. Options passed to fetch will be merged with the payload.
364
364
  | ------ | --------------------- |
365
365
  | `:key` | Key used in the store |
366
366
 
367
- INFO. Cache stores my add their own keys
367
+ INFO. Cache stores may add their own keys
368
368
 
369
369
  ```ruby
370
370
  {
@@ -457,6 +457,7 @@ Most times you only care about the data itself. Here is a shortcut to just get t
457
457
  ActiveSupport::Notifications.subscribe "process_action.action_controller" do |*args|
458
458
  data = args.extract_options!
459
459
  data # { extra: :information }
460
+ end
460
461
  ```
461
462
 
462
463
  You may also subscribe to events matching a regular expression. This enables you to subscribe to
@@ -13,7 +13,19 @@ After reading this guide, you will know:
13
13
  RDoc
14
14
  ----
15
15
 
16
- The Rails API documentation is generated with RDoc. Please consult the documentation for help with the [markup](http://rdoc.rubyforge.org/RDoc/Markup.html), and also take into account these [additional directives](http://rdoc.rubyforge.org/RDoc/Parser/Ruby.html).
16
+ The [Rails API documentation](http://api.rubyonrails.org) is generated with
17
+ [RDoc](http://docs.seattlerb.org/rdoc/).
18
+
19
+ ```bash
20
+ bundle exec rake rdoc
21
+ ```
22
+
23
+ Resulting HTML files can be found in the ./doc/rdoc directory.
24
+
25
+ Please consult the RDoc documentation for help with the
26
+ [markup](http://docs.seattlerb.org/rdoc/RDoc/Markup.html),
27
+ and also take into account these [additional
28
+ directives](http://docs.seattlerb.org/rdoc/RDoc/Parser/Ruby.html).
17
29
 
18
30
  Wording
19
31
  -------
@@ -67,7 +79,7 @@ used. Instead of:
67
79
  English
68
80
  -------
69
81
 
70
- Please use American English (<em>color</em>, <em>center</em>, <em>modularize</em>, etc). See [a list of American and British English spelling differences here](http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences).
82
+ Please use American English (*color*, *center*, *modularize*, etc). See [a list of American and British English spelling differences here](http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences).
71
83
 
72
84
  Example Code
73
85
  ------------
@@ -110,14 +122,14 @@ The results of expressions follow them and are introduced by "# => ", vertically
110
122
  If a line is too long, the comment may be placed on the next line:
111
123
 
112
124
  ```ruby
113
- # label(:post, :title)
114
- # # => <label for="post_title">Title</label>
125
+ # label(:article, :title)
126
+ # # => <label for="article_title">Title</label>
115
127
  #
116
- # label(:post, :title, "A short title")
117
- # # => <label for="post_title">A short title</label>
128
+ # label(:article, :title, "A short title")
129
+ # # => <label for="article_title">A short title</label>
118
130
  #
119
- # label(:post, :title, "A short title", class: "title_label")
120
- # # => <label for="post_title" class="title_label">A short title</label>
131
+ # label(:article, :title, "A short title", class: "title_label")
132
+ # # => <label for="article_title" class="title_label">A short title</label>
121
133
  ```
122
134
 
123
135
  Avoid using any printing methods like `puts` or `p` for that purpose.
@@ -175,8 +187,8 @@ end
175
187
  The API is careful not to commit to any particular value, the method has
176
188
  predicate semantics, that's enough.
177
189
 
178
- Filenames
179
- ---------
190
+ File Names
191
+ ----------
180
192
 
181
193
  As a rule of thumb, use filenames relative to the application root:
182
194
 
@@ -215,6 +227,13 @@ ordinary method names, symbols, paths (with forward slashes), etc. Please use
215
227
  `<tt>...</tt>` for everything else, notably class or module names with a
216
228
  namespace as in `<tt>ActiveRecord::Base</tt>`.
217
229
 
230
+ You can quickly test the RDoc output with the following command:
231
+
232
+ ```
233
+ $ echo "+:to_param+" | rdoc --pipe
234
+ #=> <p><code>:to_param</code></p>
235
+ ```
236
+
218
237
  ### Regular Font
219
238
 
220
239
  When "true" and "false" are English words rather than Ruby keywords use a regular font:
@@ -283,7 +302,7 @@ self.class_eval %{
283
302
  Method Visibility
284
303
  -----------------
285
304
 
286
- When writing documentation for Rails, it's important to understand the difference between public API (or User-facing) vs. internal API.
305
+ When writing documentation for Rails, it's important to understand the difference between public user-facing API vs internal API.
287
306
 
288
307
  Rails, like most libraries, uses the private keyword from Ruby for defining internal API. However, public API follows a slightly different convention. Instead of assuming all public methods are designed for user consumption, Rails uses the `:nodoc:` directive to annotate these kinds of methods as internal API.
289
308
 
@@ -299,17 +318,44 @@ module ActiveRecord::Core::ClassMethods
299
318
  end
300
319
  ```
301
320
 
302
- If you thought, "this method looks like a public class method for `ActiveRecord::Core`", you were right. But actually the Rails team doesn't want users to rely on this method. So they mark it as `:nodoc:` and it's removed from public documentation. The reasoning behind this is to allow the team to change these methods according to their internal needs across releases as they see fit. The name of this method could change, or the return value, or this entire class may disappear; there's no guarantee and so you shouldn't depend on this API in your plugin or application. Otherwise, you risk your app or gem breaking when you upgrade to a newer release of Rails.
321
+ If you thought, "this method looks like a public class method for `ActiveRecord::Core`", you were right. But actually the Rails team doesn't want users to rely on this method. So they mark it as `:nodoc:` and it's removed from public documentation. The reasoning behind this is to allow the team to change these methods according to their internal needs across releases as they see fit. The name of this method could change, or the return value, or this entire class may disappear; there's no guarantee and so you shouldn't depend on this API in your plugins or applications. Otherwise, you risk your app or gem breaking when you upgrade to a newer release of Rails.
303
322
 
304
- As a contributor, it's important to think about whether this API is meant for end-user consumption. The Rails team is committed to not making any breaking changes to public API across releases without going through a full deprecation cycle, which takes an eternity. It's recommended that you `:nodoc:` any of your internal methods/classes unless they're already private (meaning visibility), in which case it's internal by default. Once the API stabilizes the visibility can change from private later, but changing public API is much harder due to backwards compatibility.
323
+ As a contributor, it's important to think about whether this API is meant for end-user consumption. The Rails team is committed to not making any breaking changes to public API across releases without going through a full deprecation cycle. It's recommended that you `:nodoc:` any of your internal methods/classes unless they're already private (meaning visibility), in which case it's internal by default. Once the API stabilizes the visibility can change, but changing public API is much harder due to backwards compatibility.
305
324
 
306
325
  A class or module is marked with `:nodoc:` to indicate that all methods are internal API and should never be used directly.
307
326
 
308
- If you come across an existing `:nodoc:` you should tread lightly. Consider asking someone from the core team or author of the code before removing it. This should almost always happen through a Pull Request process instead of the docrails project.
327
+ If you come across an existing `:nodoc:` you should tread lightly. Consider asking someone from the core team or author of the code before removing it. This should almost always happen through a pull request instead of the docrails project.
309
328
 
310
329
  A `:nodoc:` should never be added simply because a method or class is missing documentation. There may be an instance where an internal public method wasn't given a `:nodoc:` by mistake, for example when switching a method from private to public visibility. When this happens it should be discussed over a PR on a case-by-case basis and never committed directly to docrails.
311
330
 
312
- To summarize, the Rails team uses `:nodoc:` to mark publicly visible methods and classes for internal use; changes to the visibility of API should be considered carefully and discussed over a Pull Request first.
331
+ To summarize, the Rails team uses `:nodoc:` to mark publicly visible methods and classes for internal use; changes to the visibility of API should be considered carefully and discussed over a pull request first.
332
+
333
+ Regarding the Rails Stack
334
+ -------------------------
335
+
336
+ When documenting parts of Rails API, it's important to remember all of the
337
+ pieces that go into the Rails stack.
338
+
339
+ This means that behavior may change depending on the scope or context of the
340
+ method or class you're trying to document.
341
+
342
+ In various places there is different behavior when you take the entire stack
343
+ into account, one such example is
344
+ `ActionView::Helpers::AssetTagHelper#image_tag`:
345
+
346
+ ```ruby
347
+ # image_tag("icon.png")
348
+ # # => <img alt="Icon" src="/assets/icon.png" />
349
+ ```
350
+
351
+ Although the default behavior for `#image_tag` is to always return
352
+ `/images/icon.png`, we take into account the full Rails stack (including the
353
+ Asset Pipeline) we may see the result seen above.
354
+
355
+ We're only concerned with the behavior experienced when using the full default
356
+ Rails stack.
313
357
 
314
- For whatever reason, you have a question on how the Rails team handles certain API don't hesitate to open a ticket or send a patch to the [issue tracker](https://github.com/rails/rails/issues).
358
+ In this case, we want to document the behavior of the _framework_, and not just
359
+ this specific method.
315
360
 
361
+ If you have a question on how the Rails team handles certain API, don't hesitate to open a ticket or send a patch to the [issue tracker](https://github.com/rails/rails/issues).