update docslcg/package-lazy-monads

2 files changed, 39 insertions, 14 deletions

diff --git a/lib/chef/decorator/lazy.rb b/lib/chef/decorator/lazy.rb
index 067d6bd7f8..71a2151d65 100644
--- a/lib/chef/decorator/lazy.rb
+++ b/lib/chef/decorator/lazy.rb
@@ -23,15 +23,25 @@ class Chef
     # called against the object.
     #
     # @example
-    #   a = Chef::Decorator::Lazy.new { puts "allocated" }
-    #   puts "start"
-    #   puts a.class
+    #
+    #     def foo
+    #       puts "allocated"
+    #       "value"
+    #     end
+    #
+    #     a = Chef::Decorator::Lazy.new { foo }
+    #
+    #     puts "started"
+    #     a
+    #     puts "still lazy"
+    #     puts a
     #
     #   outputs:
     #
-    #   start
-    #   allocated
-    #   String
+    #     started
+    #     still lazy
+    #     allocated
+    #     value
     #
     # @since 12.10.x
     class Lazy < Decorator
diff --git a/lib/chef/decorator/lazy_array.rb b/lib/chef/decorator/lazy_array.rb
index 5c21d17ce6..dc8ea832ee 100644
--- a/lib/chef/decorator/lazy_array.rb
+++ b/lib/chef/decorator/lazy_array.rb
@@ -19,19 +19,34 @@ require "chef/decorator/lazy"
 
 class Chef
   class Decorator
-    # Lazy wrapper to delay construction of an object until a method is
-    # called against the object.
+    # Lazy Array around Lazy Objects
+    #
+    # This only lazys access through `#[]`.  In order to implement #each we need to
+    # know how many items we have and what their indexes are, so we'd have to evalute
+    # the proc which makes that impossible.  You can call methods like #each and the
+    # decorator will forward the method, but item access will not be lazy.
+    #
+    # #at() and #fetch() are not implemented but technically could be.
     #
     # @example
-    #   a = Chef::Decorator::Lazy.new { puts "allocated" }
-    #   puts "start"
-    #   puts a.class
+    #     def foo
+    #         puts "allocated"
+    #           "value"
+    #     end
+    #
+    #     a = Chef::Decorator::LazyArray.new { [ foo ] }
+    #
+    #     puts "started"
+    #     a[0]
+    #     puts "still lazy"
+    #     puts a[0]
     #
     #   outputs:
     #
-    #   start
-    #   allocated
-    #   String
+    #     started
+    #     still lazy
+    #     allocated
+    #     value
     #
     # @since 12.10.x
     class LazyArray < Lazy