core: add doc examples
parent
d5fc2d8e75
commit
5698cb2bcb
4
Makefile
4
Makefile
|
@ -25,3 +25,7 @@ test: check lint
|
|||
.PHONY: rustdoc
|
||||
rustdoc:
|
||||
@RUSTDOCFLAGS="--html-before-content ./.github/doc_extra.html" cargo doc --workspace --all-features --no-deps --document-private-items
|
||||
|
||||
.PHONY: rustdoc-open
|
||||
rustdoc-open:
|
||||
@RUSTDOCFLAGS="--html-before-content ./.github/doc_extra.html" cargo doc --workspace --all-features --no-deps --document-private-items --open
|
||||
|
|
|
@ -138,6 +138,41 @@ impl Connection {
|
|||
/// `Connection` supports a limited subset of operations by default (see
|
||||
/// [`Connection::untrusted`]).
|
||||
/// Use [`Connection::trusted`] to remove these limits.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use mailpot::{Connection, Configuration};
|
||||
/// use melib::smtp::{SmtpServerConf, SmtpAuth, SmtpSecurity};
|
||||
/// #
|
||||
/// # fn main() -> mailpot::Result<()> {
|
||||
/// # use tempfile::TempDir;
|
||||
/// #
|
||||
/// # let tmp_dir = TempDir::new()?;
|
||||
/// # let db_path = tmp_dir.path().join("mpot.db");
|
||||
/// # let data_path = tmp_dir.path().to_path_buf();
|
||||
/// let config = Configuration {
|
||||
/// send_mail: mailpot::SendMail::Smtp(
|
||||
/// SmtpServerConf {
|
||||
/// hostname: "127.0.0.1".into(),
|
||||
/// port: 25,
|
||||
/// envelope_from: "foo-chat@example.com".into(),
|
||||
/// auth: SmtpAuth::None,
|
||||
/// security: SmtpSecurity::None,
|
||||
/// extensions: Default::default(),
|
||||
/// }
|
||||
/// ),
|
||||
/// db_path,
|
||||
/// data_path,
|
||||
/// administrators: vec![],
|
||||
/// };
|
||||
/// # assert_eq!(&Connection::open_db(config.clone()).unwrap_err().to_string(), "Database doesn't exist");
|
||||
///
|
||||
/// let db = Connection::open_or_create_db(config)?;
|
||||
/// # _ = db;
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
/// ```
|
||||
pub fn open_db(conf: Configuration) -> Result<Self> {
|
||||
use std::sync::Once;
|
||||
|
||||
|
|
|
@ -0,0 +1,52 @@
|
|||
# use mailpot::{*, models::*};
|
||||
# use melib::smtp::{SmtpServerConf, SmtpAuth, SmtpSecurity};
|
||||
#
|
||||
# use tempfile::TempDir;
|
||||
#
|
||||
# let tmp_dir = TempDir::new()?;
|
||||
# let db_path = tmp_dir.path().join("mpot.db");
|
||||
# let data_path = tmp_dir.path().to_path_buf();
|
||||
# let config = Configuration {
|
||||
# send_mail: mailpot::SendMail::Smtp(
|
||||
# SmtpServerConf {
|
||||
# hostname: "127.0.0.1".into(),
|
||||
# port: 25,
|
||||
# envelope_from: "foo-chat@example.com".into(),
|
||||
# auth: SmtpAuth::None,
|
||||
# security: SmtpSecurity::None,
|
||||
# extensions: Default::default(),
|
||||
# }
|
||||
# ),
|
||||
# db_path,
|
||||
# data_path,
|
||||
# administrators: vec![],
|
||||
# };
|
||||
# let db = Connection::open_or_create_db(config)?.trusted();
|
||||
# let list = db
|
||||
# .create_list(MailingList {
|
||||
# pk: 5,
|
||||
# name: "foobar chat".into(),
|
||||
# id: "foo-chat".into(),
|
||||
# address: "foo-chat@example.com".into(),
|
||||
# description: Some("Hello world, from foo-chat list".into()),
|
||||
# archive_url: Some("https://lists.example.com".into()),
|
||||
# })
|
||||
# .unwrap();
|
||||
# let sub_policy = SubscriptionPolicy {
|
||||
# pk: 1,
|
||||
# list: 5,
|
||||
# send_confirmation: true,
|
||||
# open: false,
|
||||
# manual: false,
|
||||
# request: true,
|
||||
# custom: false,
|
||||
# };
|
||||
# let post_policy = PostPolicy {
|
||||
# pk: 1,
|
||||
# list: 5,
|
||||
# announce_only: false,
|
||||
# subscription_only: false,
|
||||
# approval_needed: false,
|
||||
# open: true,
|
||||
# custom: false,
|
||||
# };
|
|
@ -28,6 +28,18 @@ use std::borrow::Cow;
|
|||
use melib::email::Address;
|
||||
|
||||
/// A database entry and its primary key. Derefs to its inner type.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// # use mailpot::{*, models::*};
|
||||
/// # fn foo(db: &Connection) {
|
||||
/// let val: Option<DbVal<MailingList>> = db.list(5).unwrap();
|
||||
/// if let Some(list) = val {
|
||||
/// assert_eq!(list.pk(), 5);
|
||||
/// }
|
||||
/// # }
|
||||
/// ```
|
||||
#[derive(Debug, PartialEq, Eq, Clone, Deserialize, Serialize)]
|
||||
#[serde(transparent)]
|
||||
pub struct DbVal<T>(pub T, #[serde(skip)] pub i64);
|
||||
|
@ -105,13 +117,34 @@ impl std::fmt::Display for MailingList {
|
|||
}
|
||||
|
||||
impl MailingList {
|
||||
/// Mailing list display name (e.g. `list name <list_address@example.com>`).
|
||||
/// Mailing list display name.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// # fn main() -> mailpot::Result<()> {
|
||||
#[doc = include_str!("./doctests/db_setup.rs.inc")]
|
||||
/// assert_eq!(
|
||||
/// &list.display_name(),
|
||||
/// "\"foobar chat\" <foo-chat@example.com>"
|
||||
/// );
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
pub fn display_name(&self) -> String {
|
||||
format!("\"{}\" <{}>", self.name, self.address)
|
||||
}
|
||||
|
||||
#[inline]
|
||||
/// Request subaddress.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// # fn main() -> mailpot::Result<()> {
|
||||
#[doc = include_str!("./doctests/db_setup.rs.inc")]
|
||||
/// assert_eq!(&list.request_subaddr(), "foo-chat+request@example.com");
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
pub fn request_subaddr(&self) -> String {
|
||||
let p = self.address.split('@').collect::<Vec<&str>>();
|
||||
format!("{}+request@{}", p[0], p[1])
|
||||
|
@ -120,6 +153,17 @@ impl MailingList {
|
|||
/// Value of `List-Id` header.
|
||||
///
|
||||
/// See RFC2919 Section 3: <https://www.rfc-editor.org/rfc/rfc2919>
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// # fn main() -> mailpot::Result<()> {
|
||||
#[doc = include_str!("./doctests/db_setup.rs.inc")]
|
||||
/// assert_eq!(
|
||||
/// &list.id_header(),
|
||||
/// "Hello world, from foo-chat list <foo-chat.example.com>");
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
pub fn id_header(&self) -> String {
|
||||
let p = self.address.split('@').collect::<Vec<&str>>();
|
||||
format!(
|
||||
|
@ -134,6 +178,18 @@ impl MailingList {
|
|||
/// Value of `List-Help` header.
|
||||
///
|
||||
/// See RFC2369 Section 3.1: <https://www.rfc-editor.org/rfc/rfc2369#section-3.1>
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// # fn main() -> mailpot::Result<()> {
|
||||
#[doc = include_str!("./doctests/db_setup.rs.inc")]
|
||||
/// assert_eq!(
|
||||
/// &list.help_header().unwrap(),
|
||||
/// "<mailto:foo-chat+request@example.com?subject=help>"
|
||||
/// );
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
pub fn help_header(&self) -> Option<String> {
|
||||
Some(format!("<mailto:{}?subject=help>", self.request_subaddr()))
|
||||
}
|
||||
|
@ -141,6 +197,19 @@ impl MailingList {
|
|||
/// Value of `List-Post` header.
|
||||
///
|
||||
/// See RFC2369 Section 3.4: <https://www.rfc-editor.org/rfc/rfc2369#section-3.4>
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// # fn main() -> mailpot::Result<()> {
|
||||
#[doc = include_str!("./doctests/db_setup.rs.inc")]
|
||||
/// assert_eq!(&list.post_header(None).unwrap(), "NO");
|
||||
/// assert_eq!(
|
||||
/// &list.post_header(Some(&post_policy)).unwrap(),
|
||||
/// "<mailto:foo-chat@example.com>"
|
||||
/// );
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
pub fn post_header(&self, policy: Option<&PostPolicy>) -> Option<String> {
|
||||
Some(policy.map_or_else(
|
||||
|| "NO".to_string(),
|
||||
|
@ -157,18 +226,26 @@ impl MailingList {
|
|||
/// Value of `List-Unsubscribe` header.
|
||||
///
|
||||
/// See RFC2369 Section 3.2: <https://www.rfc-editor.org/rfc/rfc2369#section-3.2>
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// # fn main() -> mailpot::Result<()> {
|
||||
#[doc = include_str!("./doctests/db_setup.rs.inc")]
|
||||
/// assert_eq!(
|
||||
/// &list.unsubscribe_header(Some(&sub_policy)).unwrap(),
|
||||
/// "<mailto:foo-chat+request@example.com?subject=unsubscribe>"
|
||||
/// );
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
pub fn unsubscribe_header(&self, policy: Option<&SubscriptionPolicy>) -> Option<String> {
|
||||
policy.map_or_else(
|
||||
|| None,
|
||||
|p| {
|
||||
if p.open {
|
||||
None
|
||||
} else {
|
||||
Some(format!(
|
||||
"<mailto:{}?subject=unsubscribe>",
|
||||
self.request_subaddr()
|
||||
))
|
||||
}
|
||||
|_| {
|
||||
Some(format!(
|
||||
"<mailto:{}?subject=unsubscribe>",
|
||||
self.request_subaddr()
|
||||
))
|
||||
},
|
||||
)
|
||||
}
|
||||
|
@ -176,18 +253,27 @@ impl MailingList {
|
|||
/// Value of `List-Subscribe` header.
|
||||
///
|
||||
/// See RFC2369 Section 3.3: <https://www.rfc-editor.org/rfc/rfc2369#section-3.3>
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// # fn main() -> mailpot::Result<()> {
|
||||
#[doc = include_str!("./doctests/db_setup.rs.inc")]
|
||||
/// assert_eq!(
|
||||
/// &list.subscribe_header(Some(&sub_policy)).unwrap(),
|
||||
/// "<mailto:foo-chat+request@example.com?subject=subscribe>",
|
||||
/// );
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
/// ```
|
||||
pub fn subscribe_header(&self, policy: Option<&SubscriptionPolicy>) -> Option<String> {
|
||||
policy.map_or_else(
|
||||
|| None,
|
||||
|p| {
|
||||
if p.open {
|
||||
None
|
||||
} else {
|
||||
Some(format!(
|
||||
"<mailto:{}?subject=subscribe>",
|
||||
self.request_subaddr()
|
||||
))
|
||||
}
|
||||
|_| {
|
||||
Some(format!(
|
||||
"<mailto:{}?subject=subscribe>",
|
||||
self.request_subaddr()
|
||||
))
|
||||
},
|
||||
)
|
||||
}
|
||||
|
@ -195,6 +281,19 @@ impl MailingList {
|
|||
/// Value of `List-Archive` header.
|
||||
///
|
||||
/// See RFC2369 Section 3.6: <https://www.rfc-editor.org/rfc/rfc2369#section-3.6>
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// # fn main() -> mailpot::Result<()> {
|
||||
#[doc = include_str!("./doctests/db_setup.rs.inc")]
|
||||
/// assert_eq!(
|
||||
/// &list.archive_header().unwrap(),
|
||||
/// "<https://lists.example.com>"
|
||||
/// );
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
/// ```
|
||||
pub fn archive_header(&self) -> Option<String> {
|
||||
self.archive_url.as_ref().map(|url| format!("<{}>", url))
|
||||
}
|
||||
|
|
Loading…
Reference in New Issue