From 57cc44368c46ab0c1b3d44d9aa843699c00fa130 Mon Sep 17 00:00:00 2001 From: Paul Woolcock Date: Thu, 30 Aug 2018 06:33:26 -0400 Subject: [PATCH] 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 | 29 +++++++++++++++ src/entities/account.rs | 3 ++ src/entities/list.rs | 1 + src/entities/mention.rs | 1 + src/entities/mod.rs | 18 +++++++-- src/http_send.rs | 6 +++ src/lib.rs | 2 +- src/page.rs | 7 +++- src/registration.rs | 11 ++++++ src/requests/mod.rs | 1 + src/requests/statuses.rs | 80 ++++++++++++++++++++++++++++++++++++++++ 11 files changed, 153 insertions(+), 6 deletions(-) diff --git a/src/apps.rs b/src/apps.rs index 94e85c6..2607a21 100644 --- a/src/apps.rs +++ b/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() } diff --git a/src/entities/account.rs b/src/entities/account.rs index ba6f993..e787df5 100644 --- a/src/entities/account.rs +++ b/src/entities/account.rs @@ -82,6 +82,7 @@ fn string_or_bool<'de, D: Deserializer<'de>>(val: D) -> ::std::result::Result { 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
{ let mut form = Form::new(); macro_rules! add_to_form { diff --git a/src/entities/list.rs b/src/entities/list.rs index 77ee53a..e4c5698 100644 --- a/src/entities/list.rs +++ b/src/entities/list.rs @@ -1,3 +1,4 @@ +/// Used for ser/de of list resources #[derive(Clone, Debug, Deserialize)] pub struct List { id: String, diff --git a/src/entities/mention.rs b/src/entities/mention.rs index 4f1126d..517fda5 100644 --- a/src/entities/mention.rs +++ b/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) diff --git a/src/entities/mod.rs b/src/entities/mod.rs index f7edd2a..9d73d8b 100644 --- a/src/entities/mod.rs +++ b/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}, diff --git a/src/http_send.rs b/src/http_send.rs index 52f0704..b81bb14 100644 --- a/src/http_send.rs +++ b/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; + + /// Convenience method so that .build() doesn't have to be called at every + /// call site fn send(&self, client: &Client, builder: &mut RequestBuilder) -> Result { let request = builder.build()?; self.execute(client, request) } } +#[doc(hidden)] #[derive(Clone, Copy, Debug, PartialEq)] pub struct HttpSender; diff --git a/src/lib.rs b/src/lib.rs index b75e601..4899180 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -26,7 +26,7 @@ //! ``` #![deny( - // missing_docs, + missing_docs, warnings, missing_debug_implementations, missing_copy_implementations, diff --git a/src/page.rs b/src/page.rs index d9f1b43..32ba048 100644 --- a/src/page.rs +++ b/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, @@ -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>> { 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, response: Response) -> Result { + pub(crate) fn new(mastodon: &'a Mastodon, response: Response) -> Result { let (prev, next) = get_links(&response)?; Ok(Page { initial_items: deserialise(response)?, diff --git a/src/registration.rs b/src/registration.rs index a4829d1..af47b37 100644 --- a/src/registration.rs +++ b/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>>(&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>>(&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>>(&mut self, website: I) -> &mut Self { self.app_builder.website(website); self @@ -216,6 +225,8 @@ impl Registered { } } +/// 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 { base: String, diff --git a/src/requests/mod.rs b/src/requests/mod.rs index 3db9101..f323806 100644 --- a/src/requests/mod.rs +++ b/src/requests/mod.rs @@ -1 +1,2 @@ +/// Data structures for the MastodonClient::statuses method pub mod statuses; diff --git a/src/requests/statuses.rs b/src/requests/statuses.rs index e80e8f1..18190ef 100644 --- a/src/requests/statuses.rs +++ b/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>>(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>>(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![];