Reduce the visibility of ItemsIter and add docs to items_iter

src/entities/itemsiter.rs

@@ -23,7 +23,7 @@ use serde::Deserialize;
 /// # Ok(())
 /// # }
 /// ```
-pub struct ItemsIter<'a, T: Clone + for<'de> Deserialize<'de>> {
+pub(crate) struct ItemsIter<'a, T: Clone + for<'de> Deserialize<'de>> {
     page: Page<'a, T>,
     buffer: Vec<T>,
     cur_idx: usize,

src/page.rs

@@ -55,6 +55,36 @@ impl<'a, T: for<'de> Deserialize<'de>> Page<'a, T> {
 }
 
 impl<'a, T: Clone + for<'de> Deserialize<'de>> Page<'a, T> {
+    /// Returns an iterator that provides a stream of `T`s
+    ///
+    /// This abstracts away the process of iterating over each item in a page, then making an http
+    /// call, then iterating over each item in the new page, etc. The iterator provides a stream of
+    /// `T`s, calling `self.next_page()` when necessary to get more of them, until there are no more
+    /// items.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # extern crate elefren;
+    /// # use std::error::Error;
+    /// use elefren::prelude::*;
+    /// # fn main() -> Result<(), Box<Error>> {
+    /// #   let data = Data {
+    /// #       base: "".into(),
+    /// #       client_id: "".into(),
+    /// #       client_secret: "".into(),
+    /// #       redirect: "".into(),
+    /// #       token: "".into(),
+    /// #   };
+    /// let mastodon = Mastodon::from(data);
+    /// let req = StatusesRequest::new();
+    /// let resp = mastodon.statuses("some-id", req)?;
+    /// for status in resp.items_iter() {
+    ///     // do something with status
+    /// }
+    /// #   Ok(())
+    /// # }
+    /// ```
     pub fn items_iter(self) -> impl Iterator<Item = T> + 'a
             where T: 'a
     {