From 9d674b8182e9f180b45160424ac37731944f6061 Mon Sep 17 00:00:00 2001 From: Kartikaya Gupta Date: Sun, 10 Nov 2019 21:15:30 -0500 Subject: Add documentation --- src/addrparse.rs | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/src/addrparse.rs b/src/addrparse.rs index 7b4b5f1..e60c955 100644 --- a/src/addrparse.rs +++ b/src/addrparse.rs @@ -1,3 +1,5 @@ +/// A representation of a single mailbox. Each mailbox has +/// a routing address `addr` and an optional display name. #[derive(Debug, PartialEq)] pub struct SingleInfo { pub display_name: Option, @@ -13,6 +15,8 @@ impl SingleInfo { } } +/// A representation of a group address. It has a name and +/// a list of mailboxes. #[derive(Debug, PartialEq)] pub struct GroupInfo { pub group_name: String, @@ -28,6 +32,12 @@ impl GroupInfo { } } +/// An abstraction over the two different kinds of top-level addresses allowed +/// in email headers. Group addresses have a name and a list of mailboxes. Single +/// addresses are just a mailbox. Each mailbox consists of what you would consider +/// an email address (e.g. foo@bar.com) and optionally a display name ("Foo Bar"). +/// Groups are represented in email headers with colons and semicolons, e.g. +/// To: my-peeps: foo@peeps.org, bar@peeps.org; #[derive(Debug, PartialEq)] pub enum MailAddr { Group(GroupInfo), @@ -46,6 +56,21 @@ enum AddrParseState { TrailerComment, } +/// Convert an address field from an email header into a structured type. +/// This function handles the most common formatting of to/from/cc/bcc fields +/// found in email headers. +/// +/// # Examples +/// ``` +/// use mailparse::{addrparse, MailAddr, SingleInfo}; +/// match &addrparse("John Doe ").unwrap()[0] { +/// MailAddr::Single(info) => { +/// assert_eq!(info.display_name, Some("John Doe".to_string())); +/// assert_eq!(info.addr, "john@doe.com".to_string()); +/// } +/// _ => panic!() +/// }; +/// ``` pub fn addrparse(addrs: &str) -> Result, &'static str> { let mut it = addrs.chars(); addrparse_inner(&mut it, false) -- cgit v1.2.3