Docs for NilClass#try

1 files changed, 13 insertions, 1 deletions

diff --git a/activesupport/lib/active_support/core_ext/object/try.rb b/activesupport/lib/active_support/core_ext/object/try.rb
index 04619124a1..341a6237cb 100644
--- a/activesupport/lib/active_support/core_ext/object/try.rb
+++ b/activesupport/lib/active_support/core_ext/object/try.rb
@@ -34,7 +34,19 @@ class Object
   end
 end
 
-class NilClass #:nodoc:
+class NilClass
+  # Instances of NilClass return always +nil+
+  # It becomes specially helpful when navigating through associations that may return nil
+  #
+  # === Examples
+  #
+  # nil.try(:name) => nil
+  #
+  # Without try
+  #   @person && @person.children.first && @person.children.first.name
+  #
+  # With try
+  #   @person.try(:children).try(:first).try(:name)
   def try(*args)
     nil
   end