docs(all): Added documentation to missing parts

master
Aaron Power 7 years ago
parent 87bcc139bb
commit b445197381
  1. 20
      src/apps.rs
  2. 36
      src/entities/account.rs
  3. 25
      src/entities/attachment.rs
  4. 7
      src/entities/card.rs
  5. 6
      src/entities/context.rs
  6. 8
      src/entities/instance.rs
  7. 2
      src/entities/mod.rs
  8. 13
      src/entities/notification.rs
  9. 9
      src/entities/relationship.rs
  10. 5
      src/entities/report.rs
  11. 6
      src/entities/search_result.rs
  12. 40
      src/entities/status.rs
  13. 20
      src/lib.rs
  14. 6
      src/registration.rs
  15. 13
      src/status_builder.rs

@ -1,3 +1,5 @@
use std::fmt;
/// Builder struct for defining your application. /// Builder struct for defining your application.
/// ``` /// ```
/// let app = AppBuilder { /// let app = AppBuilder {
@ -9,16 +11,24 @@
/// ``` /// ```
#[derive(Debug, Default, Serialize)] #[derive(Debug, Default, Serialize)]
pub struct AppBuilder<'a> { pub struct AppBuilder<'a> {
/// Name of the application. Will be displayed when the user is deciding to
/// grant permission.
pub client_name: &'a str, pub client_name: &'a str,
/// Where the user should be redirected after authorization
/// (for no redirect, use `urn:ietf:wg:oauth:2.0:oob`)
pub redirect_uris: &'a str, pub redirect_uris: &'a str,
/// Permission scope of the application.
pub scopes: Scope, pub scopes: Scope,
/// URL to the homepage of your application.
#[serde(skip_serializing_if="Option::is_none")] #[serde(skip_serializing_if="Option::is_none")]
pub website: Option<&'a str>, pub website: Option<&'a str>,
} }
/// Permission scope of the application.
/// [Details on what each permission provides](//github.com/tootsuite/documentation/blob/master/Using-the-API/OAuth-details.md)
#[derive(Debug, Clone, Copy, Serialize)] #[derive(Debug, Clone, Copy, Serialize)]
pub enum Scope { pub enum Scope {
/// All Permissions, equiavlent to `read write follow` /// All Permissions, equivalent to `read write follow`
#[serde(rename = "read write follow")] #[serde(rename = "read write follow")]
All, All,
/// Only permission to add and remove followers. /// Only permission to add and remove followers.
@ -27,18 +37,22 @@ pub enum Scope {
/// Read only permissions. /// Read only permissions.
#[serde(rename = "read")] #[serde(rename = "read")]
Read, Read,
/// Read & Follow permissions.
#[serde(rename = "read follow")] #[serde(rename = "read follow")]
ReadFollow, ReadFollow,
/// Read & Write permissions.
#[serde(rename = "read write")] #[serde(rename = "read write")]
ReadWrite, ReadWrite,
/// Write only permissions.
#[serde(rename = "write")] #[serde(rename = "write")]
Write, Write,
/// Write & Follow permissions.
#[serde(rename = "write follow")] #[serde(rename = "write follow")]
WriteFollow, WriteFollow,
} }
impl ::std::fmt::Display for Scope { impl fmt::Display for Scope {
fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
use self::Scope::*; use self::Scope::*;
write!(f, "{}", match *self { write!(f, "{}", match *self {
All => "read write follow", All => "read write follow",

@ -1,19 +1,39 @@
//! A module containing everything relating to a account returned from the api.
use chrono::prelude::*; use chrono::prelude::*;
/// A struct representing an Account.
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct Account { pub struct Account {
pub id: u64, /// Equals `username` for local users, includes `@domain` for remote ones.
pub username: String,
pub acct: String, pub acct: String,
pub display_name: String, /// URL to the avatar image
pub note: String,
pub url: String,
pub avatar: String, pub avatar: String,
/// URL to the avatar static image (gif)
pub avatar_static: String, pub avatar_static: String,
pub header: String, /// The time the account was created.
pub header_static: String,
pub locked: bool,
pub created_at: DateTime<Utc>, pub created_at: DateTime<Utc>,
/// The account's display name.
pub display_name: String,
/// The number of followers for the account.
pub followers_count: u64, pub followers_count: u64,
/// The number of accounts the given account is following.
pub following_count: u64, pub following_count: u64,
/// URL to the header image.
pub header: String,
/// URL to the header static image (gif).
pub header_static: String,
/// The ID of the account.
pub id: u64,
/// Boolean for when the account cannot be followed without waiting for
/// approval first.
pub locked: bool,
/// Biography of user.
pub note: String,
/// The number of statuses the account has made.
pub statuses_count: u64, pub statuses_count: u64,
/// URL of the user's profile page (can be remote).
pub url: String,
/// The username of the account.
pub username: String,
} }

@ -1,39 +1,64 @@
//! Module containing everything related to media attachements.
/// A struct representing a media attachment.
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct Attachment { pub struct Attachment {
/// ID of the attachment.
pub id: String, pub id: String,
/// The media type of an attachment.
#[serde(rename="type")] #[serde(rename="type")]
pub media_type: MediaType, pub media_type: MediaType,
/// URL of the locally hosted version of the image.
pub url: String, pub url: String,
/// For remote images, the remote URL of the original image.
pub remote_url: Option<String>, pub remote_url: Option<String>,
/// URL of the preview image.
pub preview_url: String, pub preview_url: String,
/// Shorter URL for the image, for insertion into text
/// (only present on local images)
pub text_url: Option<String>, pub text_url: Option<String>,
/// Meta information about the attachment.
pub meta: Option<Meta>, pub meta: Option<Meta>,
/// Noop will be removed.
pub description: Option<String>, pub description: Option<String>,
} }
/// Information about the attachment itself.
#[derive(Debug, Deserialize, Clone)] #[derive(Debug, Deserialize, Clone)]
pub struct Meta { pub struct Meta {
/// Original version.
original: ImageDetails, original: ImageDetails,
/// Smaller version.
small: ImageDetails, small: ImageDetails,
} }
/// Dimensions of an attachement.
#[derive(Debug, Deserialize, Clone)] #[derive(Debug, Deserialize, Clone)]
pub struct ImageDetails { pub struct ImageDetails {
/// width of attachment.
width: u64, width: u64,
/// height of attachment.
height: u64, height: u64,
/// A string of `widthxheight`.
size: String, size: String,
/// The aspect ratio of the attachment.
aspect: f64, aspect: f64,
} }
/// The type of media attachment.
#[derive(Debug, Deserialize, Clone, Copy)] #[derive(Debug, Deserialize, Clone, Copy)]
pub enum MediaType { pub enum MediaType {
/// An image.
#[serde(rename = "image")] #[serde(rename = "image")]
Image, Image,
/// A video file.
#[serde(rename = "video")] #[serde(rename = "video")]
Video, Video,
/// A gifv format file.
#[serde(rename = "gifv")] #[serde(rename = "gifv")]
Gifv, Gifv,
/// Unknown format.
#[serde(rename = "unknown")] #[serde(rename = "unknown")]
Unknown, Unknown,
} }

@ -1,7 +1,14 @@
//! Module representing cards of statuses.
/// A card of a status.
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct Card { pub struct Card {
/// The url associated with the card.
pub url: String, pub url: String,
/// The title of the card.
pub title: String, pub title: String,
/// The card description.
pub description: String, pub description: String,
/// The image associated with the card, if any.
pub image: String, pub image: String,
} }

@ -1,7 +1,13 @@
//! A module about contexts of statuses.
use super::status::Status; use super::status::Status;
/// A context of a status returning a list of statuses it replied to and
/// statuses replied to it.
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct Context { pub struct Context {
/// Statuses that were replied to.
pub ancestors: Vec<Status>, pub ancestors: Vec<Status>,
/// Statuses that replied to this status.
pub descendants: Vec<Status>, pub descendants: Vec<Status>,
} }

@ -1,7 +1,15 @@
//! Module containing everything related to an instance.
/// A struct containing info of an instance.
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct Instance { pub struct Instance {
/// URI of the current instance
pub uri: String, pub uri: String,
/// The instance's title.
pub title: String, pub title: String,
/// A description for the instance.
pub description: String, pub description: String,
/// An email address which can be used to contact the
/// instance administrator.
pub email: String, pub email: String,
} }

@ -14,6 +14,8 @@ pub mod status;
pub struct Empty {} pub struct Empty {}
pub mod prelude { 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::Empty; pub use super::Empty;
pub use super::account::Account; pub use super::account::Account;
pub use super::attachment::{Attachment, MediaType}; pub use super::attachment::{Attachment, MediaType};

@ -1,25 +1,38 @@
//! Module containing all info about notifications.
use chrono::prelude::*; use chrono::prelude::*;
use super::account::Account; use super::account::Account;
use super::status::Status; use super::status::Status;
/// A struct containing info about a notification.
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct Notification { pub struct Notification {
/// The notification ID.
pub id: u64, pub id: u64,
/// The type of notification.
#[serde(rename = "type")] #[serde(rename = "type")]
pub notification_type: NotificationType, pub notification_type: NotificationType,
/// The time the notification was created.
pub created_at: DateTime<Utc>, pub created_at: DateTime<Utc>,
/// The Account sending the notification to the user.
pub account: Account, pub account: Account,
/// The Status associated with the notification, if applicable.
pub status: Option<Status>, pub status: Option<Status>,
} }
/// The type of notification.
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub enum NotificationType { pub enum NotificationType {
/// Someone mentioned the application client in another status.
#[serde(rename = "mention")] #[serde(rename = "mention")]
Mention, Mention,
/// Someone reblogged one of the application client's statuses.
#[serde(rename = "reblog")] #[serde(rename = "reblog")]
Reblog, Reblog,
/// Someone favourited one of the application client's statuses.
#[serde(rename = "favourite")] #[serde(rename = "favourite")]
Favourite, Favourite,
/// Someone followed the application client.
#[serde(rename = "follow")] #[serde(rename = "follow")]
Follow, Follow,
} }

@ -1,8 +1,17 @@
//! module containing everything relating to a relationship with
//! another account.
/// A struct containing information about a relationship with another account.
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct Relationship { pub struct Relationship {
/// Whether the application client follows the account.
pub following: bool, pub following: bool,
/// Whether the account follows the application client.
pub followed_by: bool, pub followed_by: bool,
/// Whether the application client blocks the account.
pub blocking: bool, pub blocking: bool,
/// Whether the application client blocks the account.
pub muting: bool, pub muting: bool,
/// Whether the application client has requested to follow the account.
pub requested: bool, pub requested: bool,
} }

@ -1,5 +1,10 @@
//! module containing information about a finished report of a user.
/// A struct containing info about a report.
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct Report { pub struct Report {
/// The ID of the report.
pub id: u64, pub id: u64,
/// The action taken in response to the report.
pub action_taken: String, pub action_taken: String,
} }

@ -1,8 +1,14 @@
//! A module containing info relating to a search result.
use super::prelude::{Account, Status}; use super::prelude::{Account, Status};
/// A struct containing results of a search.
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct SearchResult { pub struct SearchResult {
/// An array of matched Accounts.
pub accounts: Vec<Account>, pub accounts: Vec<Account>,
/// An array of matched Statuses.
pub statuses: Vec<Status>, pub statuses: Vec<Status>,
/// An array of matched hashtags, as strings.
pub hashtags: Vec<String>, pub hashtags: Vec<String>,
} }

@ -1,47 +1,85 @@
//! Module containing all info relating to a status.
use chrono::prelude::*; use chrono::prelude::*;
use super::prelude::*; use super::prelude::*;
use status_builder::Visibility; use status_builder::Visibility;
/// A status from the instance.
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct Status { pub struct Status {
/// The ID of the status.
pub id: i64, pub id: i64,
/// A Fediverse-unique resource ID.
pub uri: String, pub uri: String,
/// URL to the status page (can be remote)
pub url: String, pub url: String,
/// The Account which posted the status.
pub account: Account, pub account: Account,
/// The ID of the status this status is replying to, if the status is
/// a reply.
pub in_reply_to_id: Option<u64>, pub in_reply_to_id: Option<u64>,
/// The ID of the account this status is replying to, if the status is
/// a reply.
pub in_reply_to_account_id: Option<u64>, pub in_reply_to_account_id: Option<u64>,
/// If this status is a reblogged Status of another User.
pub reblog: Option<Box<Status>>, pub reblog: Option<Box<Status>>,
/// Body of the status; this will contain HTML
/// (remote HTML already sanitized)
pub content: String, pub content: String,
/// The time the status was created.
pub created_at: DateTime<Utc>, pub created_at: DateTime<Utc>,
/// The number of reblogs for the status.
pub reblogs_count: u64, pub reblogs_count: u64,
/// The number of favourites for the status.
pub favourites_count: u64, pub favourites_count: u64,
/// Whether the application client has reblogged the status.
pub reblogged: Option<bool>, pub reblogged: Option<bool>,
/// Whether the application client has favourited the status.
pub favourited: Option<bool>, pub favourited: Option<bool>,
pub sensitive: Option<bool>, /// Whether media attachments should be hidden by default.
pub sensitive: bool,
/// If not empty, warning text that should be displayed before the actual
/// content.
pub spoiler_text: String, pub spoiler_text: String,
/// The visibilty of the status.
pub visibility: Visibility, pub visibility: Visibility,
/// An array of attachments.
pub media_attachments: Vec<Attachment>, pub media_attachments: Vec<Attachment>,
/// An array of mentions.
pub mentions: Vec<Mention>, pub mentions: Vec<Mention>,
/// An array of tags.
pub tags: Vec<Tag>, pub tags: Vec<Tag>,
/// Name of application used to post status.
pub application: Option<Application>, pub application: Option<Application>,
} }
/// A mention of another user.
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct Mention { pub struct Mention {
/// URL of user's profile (can be remote).
pub url: String, pub url: String,
/// The username of the account.
pub username: String, pub username: String,
/// Equals `username` for local users, includes `@domain` for remote ones.
pub acct: String, pub acct: String,
/// Account ID.
pub id: u64, pub id: u64,
} }
/// Hashtags in the status.
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct Tag { pub struct Tag {
/// The hashtag, not including the preceding `#`.
pub name: String, pub name: String,
/// The URL of the hashtag.
pub url: String, pub url: String,
} }
/// Application details.
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct Application { pub struct Application {
/// Name of the application.
pub name: String, pub name: String,
/// Homepage URL of the application.
pub website: Option<String>, pub website: Option<String>,
} }

@ -33,6 +33,7 @@
//! ``` //! ```
#![cfg_attr(test, deny(warnings))] #![cfg_attr(test, deny(warnings))]
#![cfg_attr(test, deny(missing_docs))]
#[macro_use] extern crate serde_derive; #[macro_use] extern crate serde_derive;
#[macro_use] extern crate serde_json as json; #[macro_use] extern crate serde_json as json;
@ -64,6 +65,7 @@ use entities::prelude::*;
pub use status_builder::StatusBuilder; pub use status_builder::StatusBuilder;
pub use registration::Registration; pub use registration::Registration;
/// Convience type over `std::result::Result` with `Error` as the error type.
pub type Result<T> = std::result::Result<T, Error>; pub type Result<T> = std::result::Result<T, Error>;
macro_rules! methods { macro_rules! methods {
@ -213,6 +215,7 @@ macro_rules! route_id {
} }
/// Your mastodon application client, handles all requests to and from Mastodon.
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
pub struct Mastodon { pub struct Mastodon {
client: Client, client: Client,
@ -225,10 +228,15 @@ pub struct Mastodon {
/// to authenticate on every run. /// to authenticate on every run.
#[derive(Clone, Debug, Deserialize, Serialize)] #[derive(Clone, Debug, Deserialize, Serialize)]
pub struct Data { pub struct Data {
/// Base url of instance eg. `https://mastodon.social`.
pub base: Cow<'static, str>, pub base: Cow<'static, str>,
/// The client's id given by the instance.
pub client_id: Cow<'static, str>, pub client_id: Cow<'static, str>,
/// The client's secret given by the instance.
pub client_secret: Cow<'static, str>, pub client_secret: Cow<'static, str>,
/// Url to redirect back to your application from the instance signup.
pub redirect: Cow<'static, str>, pub redirect: Cow<'static, str>,
/// The client's access token.
pub token: Cow<'static, str>, pub token: Cow<'static, str>,
} }
@ -382,6 +390,7 @@ impl Mastodon {
(delete) delete_status: "statuses/{}" => Empty, (delete) delete_status: "statuses/{}" => Empty,
} }
/// Post a new status to the account.
pub fn new_status(&self, status: StatusBuilder) -> Result<Status> { pub fn new_status(&self, status: StatusBuilder) -> Result<Status> {
use std::io::Read; use std::io::Read;
@ -400,6 +409,7 @@ impl Mastodon {
} }
} }
/// Get the federated timeline for the instance.
pub fn get_public_timeline(&self, local: bool) -> Result<Vec<Status>> { pub fn get_public_timeline(&self, local: bool) -> Result<Vec<Status>> {
let mut url = self.route("/api/v1/timelines/public"); let mut url = self.route("/api/v1/timelines/public");
@ -410,6 +420,8 @@ impl Mastodon {
self.get(url) self.get(url)
} }
/// Get timeline filtered by a hashtag(eg. `#coffee`) either locally or
/// federated.
pub fn get_tagged_timeline(&self, hashtag: String, local: bool) -> Result<Vec<Status>> { pub fn get_tagged_timeline(&self, hashtag: String, local: bool) -> Result<Vec<Status>> {
let mut url = self.route("/api/v1/timelines/tag/"); let mut url = self.route("/api/v1/timelines/tag/");
url += &hashtag; url += &hashtag;
@ -421,6 +433,8 @@ impl Mastodon {
self.get(url) self.get(url)
} }
/// Get statuses of a single account by id. Optionally only with pictures
/// and or excluding replies.
pub fn statuses(&self, id: u64, only_media: bool, exclude_replies: bool) pub fn statuses(&self, id: u64, only_media: bool, exclude_replies: bool)
-> Result<Vec<Status>> -> Result<Vec<Status>>
{ {
@ -444,6 +458,8 @@ impl Mastodon {
} }
/// Returns the client account's relationship to a list of other accounts.
/// Such as whether they follow them or vice versa.
pub fn relationships(&self, ids: &[u64]) -> Result<Vec<Relationship>> { pub fn relationships(&self, ids: &[u64]) -> Result<Vec<Relationship>> {
let mut url = self.route("/api/v1/accounts/relationships?"); let mut url = self.route("/api/v1/accounts/relationships?");
@ -462,11 +478,15 @@ impl Mastodon {
self.get(url) self.get(url)
} }
/// Search for accounts by their name.
/// Will lookup an account remotely if the search term is in the
/// `username@domain` format and not yet in the database.
// TODO: Add a limit fn // TODO: Add a limit fn
pub fn search_accounts(&self, query: &str) -> Result<Vec<Account>> { pub fn search_accounts(&self, query: &str) -> Result<Vec<Account>> {
self.get(format!("{}/api/v1/accounts/search?q={}", self.base, query)) self.get(format!("{}/api/v1/accounts/search?q={}", self.base, query))
} }
/// Returns the current Instance.
pub fn instance(&self) -> Result<Instance> { pub fn instance(&self) -> Result<Instance> {
self.get(self.route("/api/v1/instance")) self.get(self.route("/api/v1/instance"))
} }

@ -27,6 +27,10 @@ struct AccessToken {
} }
impl Registration { impl Registration {
/// Construct a new registration process to the instance of the `base` url.
/// ```
/// let registration = Registration::new("https://mastodon.social");
/// ```
pub fn new<I: Into<String>>(base: I) -> Self { pub fn new<I: Into<String>>(base: I) -> Self {
Registration { Registration {
base: base.into(), base: base.into(),
@ -107,6 +111,8 @@ impl Registration {
} }
} }
/// Create an access token from the client id, client secret, and code
/// provided by the authorisation url.
pub fn create_access_token(self, code: String) -> Result<Mastodon> { pub fn create_access_token(self, code: String) -> Result<Mastodon> {
self.is_registered()?; self.is_registered()?;
let url = format!( let url = format!(

@ -1,19 +1,26 @@
/// A builder pattern struct for constructing a status.
#[derive(Debug, Default, Clone, Serialize)] #[derive(Debug, Default, Clone, Serialize)]
pub struct StatusBuilder { pub struct StatusBuilder {
/// The text of the status.
pub status: String, pub status: String,
/// User ids of those to reply to. /// Ids of accounts being replied to.
#[serde(skip_serializing_if="Option::is_none")] #[serde(skip_serializing_if="Option::is_none")]
pub in_reply_to_id: Option<u64>, pub in_reply_to_id: Option<u64>,
/// Ids of media attachments being attached to the status.
#[serde(skip_serializing_if="Option::is_none")] #[serde(skip_serializing_if="Option::is_none")]
pub media_ids: Option<Vec<u64>>, pub media_ids: Option<Vec<u64>>,
/// Whether current status is sensitive.
#[serde(skip_serializing_if="Option::is_none")] #[serde(skip_serializing_if="Option::is_none")]
pub sensitive: Option<bool>, pub sensitive: Option<bool>,
/// Text to precede the normal status text.
#[serde(skip_serializing_if="Option::is_none")] #[serde(skip_serializing_if="Option::is_none")]
pub spoiler_text: Option<String>, pub spoiler_text: Option<String>,
/// Visibility of the status, defaults to `Public`.
#[serde(skip_serializing_if="Option::is_none")] #[serde(skip_serializing_if="Option::is_none")]
pub visibility: Option<Visibility>, pub visibility: Option<Visibility>,
} }
/// The visibility of a status.
#[derive(Clone, Copy, Debug, Deserialize, Serialize)] #[derive(Clone, Copy, Debug, Deserialize, Serialize)]
pub enum Visibility { pub enum Visibility {
/// A Direct message to a user /// A Direct message to a user
@ -32,6 +39,10 @@ pub enum Visibility {
impl StatusBuilder { impl StatusBuilder {
/// Create a new status with text.
/// ```
/// let status = StatusBuilder::new("Hello World!".into());
/// ```
pub fn new(status: String) -> Self { pub fn new(status: String) -> Self {
StatusBuilder { StatusBuilder {
status: status, status: status,

Loading…
Cancel
Save