From 4484e221ee8f2cd9766ecfceaccbd25978da469d Mon Sep 17 00:00:00 2001 From: Edgar Date: Wed, 10 Jun 2020 13:17:37 +0200 Subject: [PATCH] more docs --- src/errors.rs | 6 ++++-- src/lib.rs | 17 +++++++++++++++++ src/orders.rs | 23 +++++++++++++++++++++++ 3 files changed, 44 insertions(+), 2 deletions(-) diff --git a/src/errors.rs b/src/errors.rs index 52852d0..28f5099 100644 --- a/src/errors.rs +++ b/src/errors.rs @@ -1,9 +1,11 @@ +//! Errors created by this crate. + use thiserror::Error; +/// A enum that represents the possible errors. #[derive(Debug, Error)] pub enum Errors { - #[error("failed to get access token")] - GetAccessTokenFailure, + /// A error used when a api call fails. #[error("failure when calling the paypal api")] ApiCallFailure(String), } \ No newline at end of file diff --git a/src/lib.rs b/src/lib.rs index b637555..dab62e1 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,17 @@ +//! # paypal-rs +//! ![Rust](https://github.com/edg-l/paypal-rs/workflows/Rust/badge.svg) +//! ![Docs](https://docs.rs/paypal-rs/badge.svg) +//! +//! A rust library that wraps the [paypal api](https://developer.paypal.com/docs/api) asynchronously in a strongly typed manner. +//! +//! Crate: https://crates.io/crates/paypal-rs +//! +//! Documentation: https://docs.rs/paypal-rs +//! +//! Currently in early development. + +#![warn(missing_docs)] + #[cfg(test)] mod tests; @@ -11,7 +25,9 @@ use reqwest::header::HeaderMap; use serde::{Deserialize, Serialize}; use std::time::{Duration, Instant}; +/// The paypal api endpoint used on a live application. pub const LIVE_ENDPOINT: &str = "https://api.paypal.com"; +/// The paypal api endpoint used on when testing. pub const SANDBOX_ENDPOINT: &str = "https://api.sandbox.paypal.com"; /// Represents the access token returned by the OAuth2 authentication. @@ -104,6 +120,7 @@ pub struct Query { // TODO: Use https://github.com/samscott89/serde_qs } +/// The preferred server response upon successful completion of the request. #[derive(Debug, Eq, PartialEq)] pub enum Prefer { /// The server returns a minimal response to optimize communication between the API caller and the server. diff --git a/src/orders.rs b/src/orders.rs index d1142dc..561da3f 100644 --- a/src/orders.rs +++ b/src/orders.rs @@ -1,3 +1,9 @@ +//! An order represents a payment between two or more parties. +//! +//! Use the Orders API to create, update, retrieve, authorize, and capture orders. +//! +//! Reference: https://developer.paypal.com/docs/api/orders/v2/ + use crate::errors; use serde::{Deserialize, Serialize}; @@ -38,6 +44,7 @@ pub struct PayerName { /// https://developer.paypal.com/docs/api/orders/v2/#definition-phone_with_type #[derive(Debug, Serialize, Deserialize, Eq, PartialEq)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] +#[allow(missing_docs)] pub enum PhoneType { Fax, Home, @@ -46,6 +53,7 @@ pub enum PhoneType { Pager, } +/// The phone number, in its canonical international E.164 numbering plan format. #[derive(Debug, Serialize, Deserialize, Eq, PartialEq)] pub struct PhoneNumber { /// The national number, in its canonical international E.164 numbering plan format. @@ -58,11 +66,14 @@ pub struct PhoneNumber { /// Contact Telephone Number option in the Profile & Settings for the merchant's PayPal account. #[derive(Debug, Serialize, Deserialize)] pub struct Phone { + /// The phone type. #[serde(skip_serializing_if = "Option::is_none")] pub phone_type: Option, + /// The phone number pub phone_number: PhoneNumber, } +/// The customer's tax ID type. Supported for the PayPal payment method only. #[derive(Debug, Serialize, Deserialize, Eq, PartialEq)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] #[allow(non_camel_case_types)] @@ -73,6 +84,7 @@ pub enum TaxIdType { BR_CNPJ, } +/// The tax information of the payer. #[derive(Debug, Serialize, Deserialize)] pub struct TaxInfo { /// The customer's tax ID. Supported for the PayPal payment method only. @@ -82,6 +94,7 @@ pub struct TaxInfo { pub tax_id_type: TaxIdType, } +/// The address of the payer. #[derive(Debug, Default, Serialize, Deserialize)] pub struct Address { /// The first line of the address. For example, number or street. For example, 173 Drury Lane. @@ -134,6 +147,7 @@ pub struct Payer { pub address: Option
, } +/// Represents money #[derive(Debug, Serialize, Deserialize, Eq, PartialEq)] pub struct Money { /// The [three-character ISO-4217 currency code](https://developer.paypal.com/docs/integration/direct/rest/currency-codes/) that identifies the currency. @@ -173,6 +187,7 @@ pub struct Breakdown { pub discount: Option, } +/// Represents an amount of money. #[derive(Debug, Default, Serialize, Deserialize)] pub struct Amount { /// The [three-character ISO-4217 currency code](https://developer.paypal.com/docs/integration/direct/rest/currency-codes/) that identifies the currency. @@ -232,6 +247,7 @@ impl Default for DisbursementMode { } } +/// Any additional payment instructions for PayPal Commerce Platform customers. #[derive(Debug, Default, Serialize, Deserialize)] pub struct PaymentInstruction { /// An array of various fees, commissions, tips, or donations. @@ -242,6 +258,7 @@ pub struct PaymentInstruction { pub disbursement_mode: Option, } +/// The item category type. #[derive(Debug, Serialize, Deserialize, Eq, PartialEq)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] pub enum ItemCategoryType { @@ -259,14 +276,18 @@ impl Default for ItemCategoryType { } } +/// The name and address of the person to whom to ship the items. #[derive(Debug, Default, Serialize, Deserialize)] pub struct ShippingDetail { + /// The name of the person to whom to ship the items. Supports only the full_name property. #[serde(skip_serializing_if = "Option::is_none")] pub name: Option, + /// The address of the person to whom to ship the items. #[serde(skip_serializing_if = "Option::is_none")] pub address: Option
, } +/// Represents an item. #[derive(Debug, Serialize, Deserialize)] pub struct Item { /// The item name or title. @@ -658,6 +679,7 @@ pub enum CardBrand { #[derive(Debug, Serialize, Deserialize, Eq, PartialEq)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] +#[allow(missing_docs)] pub enum CardType { Credit, Debit, @@ -704,6 +726,7 @@ pub enum OrderStatus { #[derive(Debug, Serialize, Deserialize, Eq, PartialEq)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] +#[allow(missing_docs)] pub enum LinkMethod { Get, Post,