Merge pull request #1387 from rackspace/pagediterable-javadoc

Updated Javadoc for PagedIterable.

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.
- * 
+ * </p>
- * Simplest usage is to employ the {@link #concat} convenience function, and one
+ * Simplest usage is to employ the {@link #concat} convenience function, and iterate.
- * of the methods from {@link FluentIterable}.
+ * </p>
- * 
  * <pre>
- *    // pull in new pages until it we see something interesting.
+ * FluentIterable<? extends Image> images = imageApi.listInDetail().concat();
- *     Optional<StorageMetadata> firstInterestingBlob = blobstore
- *         .list(// options //)
- *         .concat()
- *         .firstMatch(isInterestingBlob());
- * </pre>
  *
- * For those seeking manual control of page advances, don't use concat, and
+ * for (Image image: images) {
- * instead look at the value of {@link IterableWithMarker#nextToken}.
+ *    System.out.println(image);
- * 
- * <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());
  * }
+ * </pre>
+ * </p> 
+ * Another usage is to employ the {@link #concat} convenience function, and one
+ * of the methods from {@link FluentIterable}.
+ * </p>
+ * <pre>
+ *    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>
  *