From bbede1bd0a289616373fd1335895f75ae278f8de Mon Sep 17 00:00:00 2001
From: Everett Toews <everett.toews@rackspace.com>
Date: Wed, 6 Mar 2013 11:51:41 -0600
Subject: [PATCH] Updated Javadoc for PagedIterable. Removed example that was
 out-of-date. Changed example to something that actually returns
 PagedIterable.

---
 .../org/jclouds/collect/PagedIterable.java    | 44 ++++++++++---------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/core/src/main/java/org/jclouds/collect/PagedIterable.java b/core/src/main/java/org/jclouds/collect/PagedIterable.java
index 738054ea1e..0e1a1a31cb 100644
--- a/core/src/main/java/org/jclouds/collect/PagedIterable.java
+++ b/core/src/main/java/org/jclouds/collect/PagedIterable.java
@@ -27,31 +27,33 @@ import com.google.common.collect.UnmodifiableIterator;
 
 /**
  * Extends {@link FluentIterable} allowing you to lazily advance through
- * sequence of pages in a resultset. Typically used in apis that return only a
+ * sequence of pages in a result set. Typically used in APIs that return only a
  * certain number of records at a time.
- * 
- * Simplest usage is to employ the {@link #concat} convenience function, and one
- * of the methods from {@link FluentIterable}.
- * 
+ * </p>
+ * Simplest usage is to employ the {@link #concat} convenience function, and iterate.
+ * </p>
  * <pre>
- *    // pull in new pages until it we see something interesting.
- *     Optional<StorageMetadata> firstInterestingBlob = blobstore
- *         .list(// options //)
- *         .concat()
- *         .firstMatch(isInterestingBlob());
+ * FluentIterable<? extends Image> images = imageApi.listInDetail().concat();
+ *
+ * for (Image image: images) {
+ *    System.out.println(image);
+ * }
  * </pre>
- * 
- * For those seeking manual control of page advances, don't use concat, and
- * instead look at the value of {@link IterableWithMarker#nextToken}.
- * 
+ * </p> 
+ * Another usage is to employ the {@link #concat} convenience function, and one
+ * of the methods from {@link FluentIterable}.
+ * </p>
  * <pre>
- * PagedIterator<StorageMetadata> blobs = blobstore.list(...).iterator();
- * while (blobs.hasNext()) {
- *     IterableWithMarker<StorageMetadata> page = blobs.next();
- *     ProcessedResults results = process(page);
- *     if (results.shouldBeBookmarked() && page.nextMarker().isPresent()) {
- *         saveBookmark(page.nextMarker().get());
- *     }
+ *    Optional<? extends Image> image = imageApi.listInDetail().concat().firstMatch(isInterestingImage());
+ *    System.out.println(image.orNull());
+ * ...
+ * private static Predicate<Image> isInterestingImage() {
+ *    return new Predicate<Image>() {
+ *       {@literal @}Override
+ *       public boolean apply(Image image) {
+ *          return image.getName().startsWith("Arch");
+ *       }
+ *    };
  * }
  * </pre>
  *