Merged pull request #279 from smerritt/each_file_doc_fix.

[storage|aws] Fix docs to say files.each, not each_file.

docs/storage/index.markdown

@@ -86,17 +86,34 @@ and maybe some pictures of your cat doing funny stuff. Since this is
 all of vital importance, you need to back it up.
 
    # copy each file to local disk
-   directory.each_file do |s3_file|
+   directory.files.each do |s3_file|
      File.open(s3_file.key, 'w') do |local_file|
        local_file.write(s3_file.body)
      end
    end
 
-One caveat: it's tempting to just write `directory.files.each` here,
-but that only works until you get a large number of files. S3's API
-for listing files forces pagination on you. `directory.each_file`
-takes pagination into account; `directory.files.each` will only
-operate on the first page.
+One caveat: it's way more efficient to do this:
+
+  # do two things per file
+  directory.files.each do |file|
+    do_one_thing(file)
+    do_another_thing(file)
+  end
+
+than it is to do this:
+
+  # do two things per file
+  directory.files.each do |file|
+    do_one_thing(file)
+  end.each do |file|
+    do_another_thing(file)
+  end
+
+The reason is that the list of files might be large. Really
+large. Eat-all-your-RAM-and-ask-for-more large. Therefore, every time
+you say `files.each`, fog makes a fresh set of API calls to Amazon to
+list the available files (Amazon's API returns a page at a time, so
+fog works a page at a time in order to keep its memory requirements sane).
 
 ## Sending it out