Document "everything"

This is a good start but many things need to be documented better, but
this will at least allow us to turn on #[deny(missing_docs)]

src/apps.rs

@@ -15,10 +15,38 @@ pub struct App {
 }
 
 impl App {
+    /// Get an AppBuilder object
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # extern crate elefren;
+    /// use elefren::apps::App;
+    ///
+    /// let mut builder = App::builder();
+    /// ```
     pub fn builder<'a>() -> AppBuilder<'a> {
         AppBuilder::new()
     }
 
+    /// Retrieve the list of scopes that apply to this App
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # extern crate elefren;
+    /// # use elefren::Error;
+    /// use elefren::apps::{App, Scopes};
+    ///
+    /// # fn main() -> Result<(), Error> {
+    /// let mut builder = App::builder();
+    /// builder.client_name("elefren-test");
+    /// let app = builder.build()?;
+    /// let scopes = app.scopes();
+    /// assert_eq!(scopes, Scopes::Read);
+    /// #   Ok(())
+    /// # }
+    /// ```
     pub fn scopes(&self) -> Scopes {
         self.scopes
     }
@@ -45,6 +73,7 @@ pub struct AppBuilder<'a> {
 }
 
 impl<'a> AppBuilder<'a> {
+    /// Creates a new AppBuilder object
     pub fn new() -> Self {
         Default::default()
     }

src/entities/account.rs

@@ -82,6 +82,7 @@ fn string_or_bool<'de, D: Deserializer<'de>>(val: D) -> ::std::result::Result<bo
     })
 }
 
+/// Data structure used for updating user credentials
 #[derive(Debug)]
 pub struct CredentialsBuilder<'a> {
     display_name: Option<&'a str>,
@@ -91,6 +92,8 @@ pub struct CredentialsBuilder<'a> {
 }
 
 impl<'a> CredentialsBuilder<'a> {
+    /// Turns a `CredentialsForm` into a form suitable for PUTing to the
+    /// endpoint
     pub fn into_form(self) -> Result<Form> {
         let mut form = Form::new();
         macro_rules! add_to_form {

src/entities/list.rs

@@ -1,3 +1,4 @@
+/// Used for ser/de of list resources
 #[derive(Clone, Debug, Deserialize)]
 pub struct List {
     id: String,

src/entities/mention.rs

@@ -1,3 +1,4 @@
+/// Represents a `mention` used in a status
 #[derive(Debug, Clone)]
 pub struct Mention {
     /// URL of user's profile (can be remote)

src/entities/mod.rs

@@ -1,25 +1,37 @@
+/// Data structures for ser/de of account-related resources
 pub mod account;
+/// Data structures for ser/de of attachment-related resources
 pub mod attachment;
+/// Data structures for ser/de of card-related resources
 pub mod card;
+/// Data structures for ser/de of contetx-related resources
 pub mod context;
+/// Data structures for ser/de of instance-related resources
 pub mod instance;
 pub(crate) mod itemsiter;
+/// Data structures for ser/de of list-related resources
 pub mod list;
+/// Data structures for ser/de of mention-related resources
 pub mod mention;
+/// Data structures for ser/de of notification-related resources
 pub mod notification;
+/// Data structures for ser/de of relationship-related resources
 pub mod relationship;
+/// Data structures for ser/de of report-related resources
 pub mod report;
+/// Data structures for ser/de of search-related resources
 pub mod search_result;
+/// Data structures for ser/de of status-related resources
 pub mod status;
 
 /// An empty JSON object.
 #[derive(Deserialize, Debug, Copy, Clone, PartialEq)]
 pub struct Empty {}
 
+/// The purpose of this module is to alleviate imports of many common
+/// structs by adding a glob import to the top of mastodon heavy
+/// modules:
 pub mod prelude {
-    //! The purpose of this module is to alleviate imports of many common
-    //! structs by adding a glob import to the top of mastodon heavy
-    //! modules:
     pub use super::{
         account::{Account, CredentialsBuilder, Source},
         attachment::{Attachment, MediaType},

src/http_send.rs

@@ -2,14 +2,20 @@ use reqwest::{Client, Request, RequestBuilder, Response};
 use std::fmt::Debug;
 use Result;
 
+/// Abstracts away the process of turning an HTTP request into an HTTP response
 pub trait HttpSend: Clone + Debug {
+    /// Converts an HTTP request into an HTTP response
     fn execute(&self, client: &Client, request: Request) -> Result<Response>;
+
+    /// Convenience method so that .build() doesn't have to be called at every
+    /// call site
     fn send(&self, client: &Client, builder: &mut RequestBuilder) -> Result<Response> {
         let request = builder.build()?;
         self.execute(client, request)
     }
 }
 
+#[doc(hidden)]
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct HttpSender;
 

src/lib.rs

@@ -26,7 +26,7 @@
 //! ```
 
 #![deny(
-    // missing_docs,
+    missing_docs,
     warnings,
     missing_debug_implementations,
     missing_copy_implementations,

src/page.rs

@@ -9,6 +9,7 @@ use url::Url;
 
 use http_send::HttpSend;
 
+/// Represents a single page of API results
 #[derive(Debug, Clone)]
 pub struct Page<'a, T: for<'de> Deserialize<'de>, H: 'a + HttpSend> {
     mastodon: &'a Mastodon<H>,
@@ -22,6 +23,8 @@ macro_rules! pages {
     ($($direction:ident: $fun:ident),*) => {
 
         $(
+            doc_comment!(concat!(
+                    "Method to retrieve the ", stringify!($direction), " page of results"),
             pub fn $fun(&mut self) -> Result<Option<Vec<T>>> {
                 let url = match self.$direction.take() {
                     Some(s) => s,
@@ -37,7 +40,7 @@ macro_rules! pages {
                 self.prev = prev;
 
                 deserialise(response)
-            }
+            });
          )*
     }
 }
@@ -48,7 +51,7 @@ impl<'a, T: for<'de> Deserialize<'de>, H: HttpSend> Page<'a, T, H> {
         prev: prev_page
     }
 
-    pub fn new(mastodon: &'a Mastodon<H>, response: Response) -> Result<Self> {
+    pub(crate) fn new(mastodon: &'a Mastodon<H>, response: Response) -> Result<Self> {
         let (prev, next) = get_links(&response)?;
         Ok(Page {
             initial_items: deserialise(response)?,

src/registration.rs

@@ -68,21 +68,30 @@ impl<'a, H: HttpSend> Registration<'a, H> {
         }
     }
 
+    /// Sets the name of this app
+    ///
+    /// This is required, and if this isn't set then the AppBuilder::build
+    /// method will fail
     pub fn client_name<I: Into<Cow<'a, str>>>(&mut self, name: I) -> &mut Self {
         self.app_builder.client_name(name.into());
         self
     }
 
+    /// Sets the redirect uris that this app uses
     pub fn redirect_uris<I: Into<Cow<'a, str>>>(&mut self, uris: I) -> &mut Self {
         self.app_builder.redirect_uris(uris);
         self
     }
 
+    /// Sets the scopes that this app requires
+    ///
+    /// The default for an app is Scopes::Read
     pub fn scopes(&mut self, scopes: Scopes) -> &mut Self {
         self.app_builder.scopes(scopes);
         self
     }
 
+    /// Sets the optional "website" to register the app with
     pub fn website<I: Into<Cow<'a, str>>>(&mut self, website: I) -> &mut Self {
         self.app_builder.website(website);
         self
@@ -216,6 +225,8 @@ impl<H: HttpSend> Registered<H> {
     }
 }
 
+/// Represents the state of the auth flow when the app has been registered but
+/// the user is not authenticated
 #[derive(Debug, Clone)]
 pub struct Registered<H: HttpSend> {
     base: String,

src/requests/mod.rs

@@ -1 +1,2 @@
+/// Data structures for the MastodonClient::statuses method
 pub mod statuses;

src/requests/statuses.rs

@@ -1,5 +1,7 @@
 use std::borrow::Cow;
 
+/// Builder for making a client.statuses() call
+///
 /// # Example
 ///
 /// ```
@@ -19,40 +21,118 @@ pub struct StatusesRequest<'a> {
 }
 
 impl<'a> StatusesRequest<'a> {
+    /// Construct a new `StatusesRequest` object
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # extern crate elefren;
+    /// # use elefren::StatusesRequest;
+    /// let request = StatusesRequest::new();
+    /// ```
     pub fn new() -> Self {
         Self::default()
     }
 
+    /// Set the `?only_media=1` flag for the .statuses() request
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # extern crate elefren;
+    /// # use elefren::StatusesRequest;
+    /// let request = StatusesRequest::new().only_media();
+    /// assert_eq!(&request.to_querystring(), "?only_media=1");
     pub fn only_media(mut self) -> Self {
         self.only_media = true;
         self
     }
 
+    /// Set the `?exclude_replies=1` flag for the .statuses() request
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # extern crate elefren;
+    /// # use elefren::StatusesRequest;
+    /// let request = StatusesRequest::new().exclude_replies();
+    /// assert_eq!(&request.to_querystring(), "?exclude_replies=1");
+    /// ```
     pub fn exclude_replies(mut self) -> Self {
         self.exclude_replies = true;
         self
     }
 
+    /// Set the `?pinned=1` flag for the .statuses() request
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # extern crate elefren;
+    /// # use elefren::StatusesRequest;
+    /// let request = StatusesRequest::new().pinned();
+    /// assert_eq!(&request.to_querystring(), "?pinned=1");
+    /// ```
     pub fn pinned(mut self) -> Self {
         self.pinned = true;
         self
     }
 
+    /// Set the `?max_id=:max_id` flag for the .statuses() request
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # extern crate elefren;
+    /// # use elefren::StatusesRequest;
+    /// let request = StatusesRequest::new().max_id("foo");
+    /// assert_eq!(&request.to_querystring(), "?max_id=foo");
+    /// ```
     pub fn max_id<S: Into<Cow<'a, str>>>(mut self, max_id: S) -> Self {
         self.max_id = Some(max_id.into());
         self
     }
 
+    /// Set the `?since_id=:since_id` flag for the .statuses() request
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # extern crate elefren;
+    /// # use elefren::StatusesRequest;
+    /// let request = StatusesRequest::new().since_id("foo");
+    /// assert_eq!(&request.to_querystring(), "?since_id=foo");
+    /// ```
     pub fn since_id<S: Into<Cow<'a, str>>>(mut self, since_id: S) -> Self {
         self.since_id = Some(since_id.into());
         self
     }
 
+    /// Set the `?limit=:limit` flag for the .statuses() request
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # extern crate elefren;
+    /// # use elefren::StatusesRequest;
+    /// let request = StatusesRequest::new().limit(10);
+    /// assert_eq!(&request.to_querystring(), "?limit=10");
+    /// ```
     pub fn limit(mut self, limit: usize) -> Self {
         self.limit = Some(limit);
         self
     }
 
+    /// Turns this builder into a querystring
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # extern crate elefren;
+    /// # use elefren::StatusesRequest;
+    /// let request = StatusesRequest::new().limit(10).pinned();
+    /// assert_eq!(&request.to_querystring(), "?pinned=1&limit=10");
+    /// ```
     pub fn to_querystring(&self) -> String {
         let mut opts = vec![];