From c3fdafde3b69c0abc78a62926e0c32fc3dd602d6 Mon Sep 17 00:00:00 2001 From: Manos Pitsidianakis Date: Mon, 26 Sep 2022 18:04:53 +0300 Subject: [PATCH] Documentation touchups --- docs/meli.1 | 57 +++++++++++++++- melib/src/addressbook/vcard.rs | 13 +++- melib/src/backends/imap/connection.rs | 2 +- melib/src/backends/maildir/backend.rs | 7 +- melib/src/backends/mbox.rs | 13 ++-- melib/src/backends/nntp.rs | 7 ++ melib/src/backends/notmuch/bindings.rs | 91 +++++++++++++++++++++++++- melib/src/email.rs | 2 +- melib/src/email/parser.rs | 4 +- melib/src/smtp.rs | 4 ++ src/mailcap.rs | 6 +- src/terminal/embed/grid.rs | 18 +++-- 12 files changed, 195 insertions(+), 29 deletions(-) diff --git a/docs/meli.1 b/docs/meli.1 index 60ad78fea..a9aa893e2 100644 --- a/docs/meli.1 +++ b/docs/meli.1 @@ -603,11 +603,64 @@ Mailcap entries are searched for in the following files, in this order: .Xr xdg-open 1 , .Xr mailcap 5 .Sh CONFORMING TO +.Bl -bullet -compact +.It XDG Standard .Lk https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html Ns -, maildir +\&. +.It +mailcap file, RFC 1524: A User Agent Configuration Mechanism For Multimedia Mail Format Information +.It +RFC 5322: Internet Message Format +.It +RFC 6532: Internationalized Email Headers +.It +RFC 2047: MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extensions for Non-ASCII Text +.It +RFC 3676: The Text/Plain Format and DelSp Parameters +.It +RFC 3156: MIME Security with OpenPGP +.It +RFC 2183: Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field +.It +RFC 2369: The Use of URLs as Meta-Syntax for Core Mail List Commands and their Transport through Message Header Fields +.It +.Li maildir .Lk https://cr.yp.to/proto/maildir.html Ns -, IMAPv4rev1 RFC3501, The JSON Meta Application Protocol (JMAP) RFC8620, The JSON Meta Application Protocol (JMAP) for Mail RFC8621. +\&. +.It +RFC 5321: Simple Mail Transfer Protocol +.It +RFC 3461: Simple Mail Transfer Protocol (SMTP) Service Extension for Delivery Status Notifications (DSNs) +.It +RFC 4954: SMTP Service Extension for Authentication +.It +RFC 6152: SMTP Service Extension for 8-bit MIME Transport +.It +RFC 4616: The PLAIN Simple Authentication and Security Layer (SASL) Mechanism +.It +RFC 3501: INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1 +.It +RFC 3691: Internet Message Access Protocol (IMAP) UNSELECT command +.It +RFC 4549: Synch Ops for Disconnected IMAP4 Clients +.It +RFC 7162: IMAP Extensions: Quick Flag Changes Resynchronization (CONDSTORE) and Quick Mailbox Resynchronization (QRESYNC) +.It +RFC 8620: The JSON Meta Application Protocol (JMAP) +.It +RFC 8621: The JSON Meta Application Protocol (JMAP) for Mail +.It +RFC 3977: Network News Transfer Protocol (NNTP) +.It +RFC 6048: Network News Transfer Protocol (NNTP) Additions to LIST Command +.It +vCard Version 3, RFC 2426: vCard MIME Directory Profile +.It +vCard Version 4, RFC 6350: vCard Format Specification +.It +RFC 6868 Parameter Value Encoding in iCalendar and vCard +.El .Sh AUTHORS Copyright 2017-2022 .An Manos Pitsidianakis Mt manos@pitsidianak.is diff --git a/melib/src/addressbook/vcard.rs b/melib/src/addressbook/vcard.rs index e3f9f5c28..35ad9c00d 100644 --- a/melib/src/addressbook/vcard.rs +++ b/melib/src/addressbook/vcard.rs @@ -19,7 +19,14 @@ * along with meli. If not, see . */ -/// Convert VCard strings to meli Cards (contacts). +//! # vCard format +//! +//! This module implements the standards: +//! +//! - Version 3 (read-only) [RFC 2426: vCard MIME Directory Profile](https://datatracker.ietf.org/doc/2426) +//! - Version 4 [RFC 6350: vCard Format Specification](https://datatracker.ietf.org/doc/rfc6350/) +//! - Parameter escaping [RFC 6868 Parameter Value Encoding in iCalendar and vCard](https://datatracker.ietf.org/doc/rfc6868/) + use super::*; use crate::error::{MeliError, Result}; use crate::parsec::{match_literal_anycase, one_or_more, peek, prefix, take_until, Parser}; @@ -33,12 +40,12 @@ pub trait VCardVersion: core::fmt::Debug {} pub struct VCardVersionUnknown; impl VCardVersion for VCardVersionUnknown {} -/// https://tools.ietf.org/html/rfc6350 +/// Version 4 #[derive(Debug)] pub struct VCardVersion4; impl VCardVersion for VCardVersion4 {} -/// https://tools.ietf.org/html/rfc2426 +/// #[derive(Debug)] pub struct VCardVersion3; impl VCardVersion for VCardVersion3 {} diff --git a/melib/src/backends/imap/connection.rs b/melib/src/backends/imap/connection.rs index 37e8e2894..faec21563 100644 --- a/melib/src/backends/imap/connection.rs +++ b/melib/src/backends/imap/connection.rs @@ -44,7 +44,7 @@ use super::{Capabilities, ImapServerConf, UIDStore}; #[derive(Debug, Clone, Copy)] pub enum SyncPolicy { None, - ///rfc4549 `Synch Ops for Disconnected IMAP4 Clients` https://tools.ietf.org/html/rfc4549 + ///rfc4549 `Synch Ops for Disconnected IMAP4 Clients` Basic, ///rfc7162 `IMAP Extensions: Quick Flag Changes Resynchronization (CONDSTORE) and Quick Mailbox Resynchronization (QRESYNC)` Condstore, diff --git a/melib/src/backends/maildir/backend.rs b/melib/src/backends/maildir/backend.rs index 573163b6b..212da2b01 100644 --- a/melib/src/backends/maildir/backend.rs +++ b/melib/src/backends/maildir/backend.rs @@ -19,6 +19,11 @@ * along with meli. If not, see . */ +//! # Maildir Backend +//! +//! This module implements a maildir backend according to the maildir specification. +//! + use super::{MaildirMailbox, MaildirOp, MaildirPathTrait}; use crate::backends::{RefreshEventKind::*, *}; use crate::conf::AccountSettings; @@ -102,7 +107,7 @@ impl DerefMut for HashIndex { pub type HashIndexes = Arc>>; -/// Maildir backend https://cr.yp.to/proto/maildir.html +/// The maildir backend instance type. #[derive(Debug)] pub struct MaildirType { name: String, diff --git a/melib/src/backends/mbox.rs b/melib/src/backends/mbox.rs index 0ff84c0ca..3ef7cfd2b 100644 --- a/melib/src/backends/mbox.rs +++ b/melib/src/backends/mbox.rs @@ -23,16 +23,17 @@ //! //! ## Resources //! -//! - [0] -//! - [1] -//! - [2] +//! [^0]: +//! [^1]: +//! [^2]: //! //! ## `mbox` format +//! //! `mbox` describes a family of incompatible legacy formats. //! -//! "All of the 'mbox' formats store all of the messages in the mailbox in a single file. Delivery appends new messages to the end of the file." [0] +//! "All of the 'mbox' formats store all of the messages in the mailbox in a single file. Delivery appends new messages to the end of the file." [^0] //! -//! "Each message is preceded by a From_ line and followed by a blank line. A From_ line is a line that begins with the five characters 'F', 'r', 'o', 'm', and ' '." [0] +//! "Each message is preceded by a From_ line and followed by a blank line. A From_ line is a line that begins with the five characters 'F', 'r', 'o', 'm', and ' '." [^0] //! //! ## `From ` / postmark line //! @@ -59,7 +60,7 @@ //! //! "In order to avoid misinterpretation of lines in message bodies which begin with the four //! characters 'From', followed by a space character, the mail delivery agent must quote -//! any occurrence of 'From ' at the start of a body line." [2] +//! any occurrence of 'From ' at the start of a body line." [^2] //! //! ## Metadata //! diff --git a/melib/src/backends/nntp.rs b/melib/src/backends/nntp.rs index d7cba6233..53dde9f4a 100644 --- a/melib/src/backends/nntp.rs +++ b/melib/src/backends/nntp.rs @@ -19,6 +19,13 @@ * along with meli. If not, see . */ +//! # NNTP backend / client +//! +//! Implements an NNTP client as specified by [RFC 3977: Network News Transfer Protocol +//! (NNTP)](https://datatracker.ietf.org/doc/html/rfc3977). Also implements [RFC 6048: Network News +//! Transfer Protocol (NNTP) Additions to LIST +//! Command](https://datatracker.ietf.org/doc/html/rfc6048). + use crate::get_conf_val; use crate::get_path_hash; use smallvec::SmallVec; diff --git a/melib/src/backends/notmuch/bindings.rs b/melib/src/backends/notmuch/bindings.rs index 57cf8a72c..8841e97b6 100644 --- a/melib/src/backends/notmuch/bindings.rs +++ b/melib/src/backends/notmuch/bindings.rs @@ -16,9 +16,11 @@ pub const _notmuch_status_NOTMUCH_STATUS_OUT_OF_MEMORY: _notmuch_status = 1; pub const _notmuch_status_NOTMUCH_STATUS_READ_ONLY_DATABASE: _notmuch_status = 2; /// A Xapian exception occurred. /// +/// ```text /// @todo We don't really want to expose this lame XAPIAN_EXCEPTION /// value. Instead we should map to things like DATABASE_LOCKED or /// whatever. +/// ``` pub const _notmuch_status_NOTMUCH_STATUS_XAPIAN_EXCEPTION: _notmuch_status = 3; /// An error occurred trying to read or write to a file (this could /// be file not found, permission denied, etc.) @@ -466,6 +468,7 @@ pub type notmuch_database_get_directory = unsafe extern "C" fn( /// /// Return value: /// +/// ```text /// NOTMUCH_STATUS_SUCCESS: Message successfully added to database. /// /// NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred, @@ -490,6 +493,7 @@ pub type notmuch_database_get_directory = unsafe extern "C" fn( /// database to use this function. /// /// @since libnotmuch 5.1 (notmuch 0.26) +/// ``` pub type notmuch_database_index_file = unsafe extern "C" fn( database: *mut notmuch_database_t, filename: *const ::std::os::raw::c_char, @@ -501,8 +505,10 @@ extern "C" { /// Deprecated alias for notmuch_database_index_file called with /// NULL indexopts. /// + /// ```text /// @deprecated Deprecated as of libnotmuch 5.1 (notmuch 0.26). Please /// use notmuch_database_index_file instead. + /// ``` /// pub fn notmuch_database_add_message( database: *mut notmuch_database_t, @@ -616,7 +622,7 @@ pub type notmuch_database_get_all_tags = /// completely in the future, but it's likely to be a specialized /// version of the general Xapian query syntax: /// -/// https://xapian.org/docs/queryparser.html +/// /// /// As a special case, passing either a length-zero string, (that is ""), /// or a string consisting of a single asterisk (that is "*"), will @@ -703,7 +709,9 @@ pub type notmuch_query_get_sort = /// This exclusion will be ignored if this tag appears explicitly in /// the query. /// +/// ```text /// @returns +/// ``` /// /// NOTMUCH_STATUS_SUCCESS: excluded was added successfully. /// @@ -757,7 +765,9 @@ pub type notmuch_query_add_tag_exclude = unsafe extern "C" fn( /// notmuch_threads_destroy function, but there's no good reason /// to call it if the query is about to be destroyed). /// +/// ```text /// @since libnotmuch 5.0 (notmuch 0.25) +/// ``` pub type notmuch_query_search_threads = unsafe extern "C" fn( query: *mut notmuch_query_t, out: *mut *mut notmuch_threads_t, @@ -765,7 +775,9 @@ pub type notmuch_query_search_threads = unsafe extern "C" fn( /// Deprecated alias for notmuch_query_search_threads. /// +/// ```text /// @deprecated Deprecated as of libnotmuch 5 (notmuch 0.25). Please +/// ``` /// use notmuch_query_search_threads instead. /// pub type notmuch_query_search_threads_st = unsafe extern "C" fn( @@ -813,7 +825,9 @@ pub type notmuch_query_search_threads_st = unsafe extern "C" fn( /// /// If a Xapian exception occurs this function will return NULL. /// +/// ```text /// @since libnotmuch 5 (notmuch 0.25) +/// ``` pub type notmuch_query_search_messages = unsafe extern "C" fn( query: *mut notmuch_query_t, out: *mut *mut notmuch_messages_t, @@ -821,7 +835,9 @@ pub type notmuch_query_search_messages = unsafe extern "C" fn( /// Deprecated alias for notmuch_query_search_messages /// +/// ```text /// @deprecated Deprecated as of libnotmuch 5 (notmuch 0.25). Please use +/// ``` /// notmuch_query_search_messages instead. /// pub type notmuch_query_search_messages_st = unsafe extern "C" fn( @@ -887,6 +903,7 @@ pub type notmuch_threads_destroy = unsafe extern "C" fn(threads: *mut notmuch_th /// This function performs a search and returns the number of matching /// messages. /// +/// ```text /// @returns /// /// NOTMUCH_STATUS_SUCCESS: query completed successfully. @@ -895,6 +912,7 @@ pub type notmuch_threads_destroy = unsafe extern "C" fn(threads: *mut notmuch_th /// value of *count is not defined. /// /// @since libnotmuch 5 (notmuch 0.25) +/// ``` pub type notmuch_query_count_messages = unsafe extern "C" fn( query: *mut notmuch_query_t, count: *mut ::std::os::raw::c_uint, @@ -902,9 +920,10 @@ pub type notmuch_query_count_messages = unsafe extern "C" fn( /// Deprecated alias for notmuch_query_count_messages /// -/// +/// ```text /// @deprecated Deprecated since libnotmuch 5.0 (notmuch 0.25). Please /// use notmuch_query_count_messages instead. +/// ``` pub type notmuch_query_count_messages_st = unsafe extern "C" fn( query: *mut notmuch_query_t, count: *mut ::std::os::raw::c_uint, @@ -919,6 +938,7 @@ pub type notmuch_query_count_messages_st = unsafe extern "C" fn( /// Note that this is a significantly heavier operation than /// notmuch_query_count_messages{_st}(). /// +/// ```text /// @returns /// /// NOTMUCH_STATUS_OUT_OF_MEMORY: Memory allocation failed. The value @@ -930,6 +950,7 @@ pub type notmuch_query_count_messages_st = unsafe extern "C" fn( /// value of *count is not defined. /// /// @since libnotmuch 5 (notmuch 0.25) +/// ``` pub type notmuch_query_count_threads = unsafe extern "C" fn( query: *mut notmuch_query_t, count: *mut ::std::os::raw::c_uint, @@ -937,8 +958,10 @@ pub type notmuch_query_count_threads = unsafe extern "C" fn( /// Deprecated alias for notmuch_query_count_threads /// +/// ```text /// @deprecated Deprecated as of libnotmuch 5.0 (notmuch 0.25). Please /// use notmuch_query_count_threads_st instead. +/// ``` pub type notmuch_query_count_threads_st = unsafe extern "C" fn( query: *mut notmuch_query_t, count: *mut ::std::os::raw::c_uint, @@ -964,8 +987,10 @@ pub type notmuch_thread_get_total_messages = /// /// This sums notmuch_message_count_files over all messages in the /// thread +/// ```text /// @returns Non-negative integer /// @since libnotmuch 5.0 (notmuch 0.25) +/// ``` pub type notmuch_thread_get_total_files = unsafe extern "C" fn(thread: *mut notmuch_thread_t) -> ::std::os::raw::c_int; @@ -1136,7 +1161,9 @@ pub type notmuch_messages_collect_tags = /// Get the database associated with this message. /// +/// ```text /// @since libnotmuch 5.2 (notmuch 0.27) +/// ``` pub type notmuch_message_get_database = unsafe extern "C" fn(message: *const notmuch_message_t) -> *mut notmuch_database_t; @@ -1188,8 +1215,10 @@ pub type notmuch_message_get_replies = unsafe extern "C" fn(message: *mut notmuch_message_t) -> *mut notmuch_messages_t; /// Get the total number of files associated with a message. +/// ```text /// @returns Non-negative integer /// @since libnotmuch 5.0 (notmuch 0.25) +/// ``` pub type notmuch_message_count_files = unsafe extern "C" fn(message: *mut notmuch_message_t) -> ::std::os::raw::c_int; @@ -1450,6 +1479,7 @@ pub type notmuch_message_tags_to_maildir_flags = /// change tag values. For example, explicitly setting a message to /// have a given set of tags might look like this: /// +/// ```c /// notmuch_message_freeze (message); /// /// notmuch_message_remove_all_tags (message); @@ -1458,6 +1488,7 @@ pub type notmuch_message_tags_to_maildir_flags = /// notmuch_message_add_tag (message, tags[i]); /// /// notmuch_message_thaw (message); +/// ``` /// /// With freeze/thaw used like this, the message in the database is /// guaranteed to have either the full set of original tag values, or @@ -1508,7 +1539,9 @@ pub type notmuch_message_thaw = /// the messages get reclaimed when the containing query is destroyed.) pub type notmuch_message_destroy = unsafe extern "C" fn(message: *mut notmuch_message_t); +/// ```text /// @name Message Properties +/// ``` /// /// This interface provides the ability to attach arbitrary (key,value) /// string pairs to a message, to remove such pairs, and to iterate @@ -1525,10 +1558,12 @@ pub type notmuch_message_destroy = unsafe extern "C" fn(message: *mut notmuch_me /// no such key. In the case of multiple values for the given key, the /// first one is retrieved. /// +/// ```text /// @returns /// - NOTMUCH_STATUS_NULL_POINTER: *value* may not be NULL. /// - NOTMUCH_STATUS_SUCCESS: No error occurred. /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_message_get_property = unsafe extern "C" fn( message: *mut notmuch_message_t, key: *const ::std::os::raw::c_char, @@ -1537,11 +1572,13 @@ pub type notmuch_message_get_property = unsafe extern "C" fn( /// Add a (key,value) pair to a message /// +/// ```text /// @returns /// - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character. /// - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL. /// - NOTMUCH_STATUS_SUCCESS: No error occurred. /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_message_add_property = unsafe extern "C" fn( message: *mut notmuch_message_t, key: *const ::std::os::raw::c_char, @@ -1552,11 +1589,13 @@ pub type notmuch_message_add_property = unsafe extern "C" fn( /// /// It is not an error to remove a non-existant (key,value) pair /// +/// ```text /// @returns /// - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character. /// - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL. /// - NOTMUCH_STATUS_SUCCESS: No error occurred. /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_message_remove_property = unsafe extern "C" fn( message: *mut notmuch_message_t, key: *const ::std::os::raw::c_char, @@ -1565,6 +1604,7 @@ pub type notmuch_message_remove_property = unsafe extern "C" fn( /// Remove all (key,value) pairs from the given message. /// +/// ```text /// @param[in,out] message message to operate on. /// @param[in] key key to delete properties for. If NULL, delete /// properties for all keys @@ -1574,6 +1614,7 @@ pub type notmuch_message_remove_property = unsafe extern "C" fn( /// - NOTMUCH_STATUS_SUCCESS: No error occurred. /// /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_message_remove_all_properties = unsafe extern "C" fn( message: *mut notmuch_message_t, key: *const ::std::os::raw::c_char, @@ -1581,6 +1622,7 @@ pub type notmuch_message_remove_all_properties = unsafe extern "C" fn( /// Remove all (prefix*,value) pairs from the given message /// +/// ```text /// @param[in,out] message message to operate on. /// @param[in] prefix delete properties with keys that start with prefix. /// If NULL, delete all properties @@ -1590,6 +1632,7 @@ pub type notmuch_message_remove_all_properties = unsafe extern "C" fn( /// - NOTMUCH_STATUS_SUCCESS: No error occurred. /// /// @since libnotmuch 5.1 (notmuch 0.26) +/// ``` pub type notmuch_message_remove_all_properties_with_prefix = unsafe extern "C" fn( message: *mut notmuch_message_t, @@ -1612,10 +1655,12 @@ extern "C" { /// as such, will only be valid for as long as the message is valid, /// (which is until the query from which it derived is destroyed). /// + /// ```text /// @param[in] message The message to examine /// @param[in] key key or key prefix /// @param[in] exact if TRUE, require exact match with key. Otherwise /// treat as prefix. + /// ``` /// /// Typical usage might be: /// @@ -1635,7 +1680,9 @@ extern "C" { /// provide a notmuch_message_properities_destroy function, but there's /// no good reason to call it if the message is about to be destroyed). /// + /// ```text /// @since libnotmuch 4.4 (notmuch 0.23) + /// ``` pub fn notmuch_message_get_properties( message: *mut notmuch_message_t, key: *const ::std::os::raw::c_char, @@ -1644,6 +1691,7 @@ extern "C" { } /// Return the number of properties named "key" belonging to the specific message. /// +/// ```text /// @param[in] message The message to examine /// @param[in] key key to count /// @param[out] count The number of matching properties associated with this message. @@ -1653,6 +1701,7 @@ extern "C" { /// NOTMUCH_STATUS_SUCCESS: successful count, possibly some other error. /// /// @since libnotmuch 5.2 (notmuch 0.27) +/// ``` pub type notmuch_message_count_properties = unsafe extern "C" fn( message: *mut notmuch_message_t, key: *const ::std::os::raw::c_char, @@ -1672,7 +1721,9 @@ pub type notmuch_message_count_properties = unsafe extern "C" fn( /// code showing how to iterate over a notmuch_message_properties_t /// object. /// +/// ```text /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_message_properties_valid = unsafe extern "C" fn(properties: *mut notmuch_message_properties_t) -> notmuch_bool_t; @@ -1685,7 +1736,9 @@ pub type notmuch_message_properties_valid = /// See the documentation of notmuch_message_get_properties for example /// code showing how to iterate over a notmuch_message_properties_t object. /// +/// ```text /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_message_properties_move_to_next = unsafe extern "C" fn(properties: *mut notmuch_message_properties_t); @@ -1693,7 +1746,9 @@ pub type notmuch_message_properties_move_to_next = /// /// this could be useful if iterating for a prefix /// +/// ```text /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_message_properties_key = unsafe extern "C" fn( properties: *mut notmuch_message_properties_t, ) -> *const ::std::os::raw::c_char; @@ -1702,7 +1757,9 @@ pub type notmuch_message_properties_key = unsafe extern "C" fn( /// /// This could be useful if iterating for a prefix. /// +/// ```text /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_message_properties_value = unsafe extern "C" fn( properties: *mut notmuch_message_properties_t, ) -> *const ::std::os::raw::c_char; @@ -1713,7 +1770,9 @@ pub type notmuch_message_properties_value = unsafe extern "C" fn( /// the notmuch_message_properties_t object will be reclaimed when the /// containing message object is destroyed. /// +/// ```text /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_message_properties_destroy = unsafe extern "C" fn(properties: *mut notmuch_message_properties_t); @@ -1821,7 +1880,9 @@ pub type notmuch_directory_get_child_directories = /// notmuch_directory_t object. Assumes any child directories and files /// have been deleted by the caller. /// +/// ```text /// @since libnotmuch 4.3 (notmuch 0.21) +/// ``` pub type notmuch_directory_delete = unsafe extern "C" fn(directory: *mut notmuch_directory_t) -> notmuch_status_t; @@ -1872,7 +1933,9 @@ pub type notmuch_filenames_destroy = unsafe extern "C" fn(filenames: *mut notmuc /// set config 'key' to 'value' /// +/// ```text /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_database_set_config = unsafe extern "C" fn( db: *mut notmuch_database_t, key: *const ::std::os::raw::c_char, @@ -1887,7 +1950,9 @@ pub type notmuch_database_set_config = unsafe extern "C" fn( /// return value is allocated by malloc and should be freed by the /// caller. /// +/// ```text /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_database_get_config = unsafe extern "C" fn( db: *mut notmuch_database_t, key: *const ::std::os::raw::c_char, @@ -1896,7 +1961,9 @@ pub type notmuch_database_get_config = unsafe extern "C" fn( /// Create an iterator for all config items with keys matching a given prefix /// +/// ```text /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_database_get_config_list = unsafe extern "C" fn( db: *mut notmuch_database_t, prefix: *const ::std::os::raw::c_char, @@ -1905,7 +1972,9 @@ pub type notmuch_database_get_config_list = unsafe extern "C" fn( /// Is 'config_list' iterator valid (i.e. _key, _value, _move_to_next can be called). /// +/// ```text /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_config_list_valid = unsafe extern "C" fn(config_list: *mut notmuch_config_list_t) -> notmuch_bool_t; @@ -1914,7 +1983,9 @@ pub type notmuch_config_list_valid = /// return value is owned by the iterator, and will be destroyed by the /// next call to notmuch_config_list_key or notmuch_config_list_destroy. /// +/// ```text /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_config_list_key = unsafe extern "C" fn(config_list: *mut notmuch_config_list_t) -> *const ::std::os::raw::c_char; @@ -1923,19 +1994,25 @@ pub type notmuch_config_list_key = /// return value is owned by the iterator, and will be destroyed by the /// next call to notmuch_config_list_value or notmuch config_list_destroy /// +/// ```text /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_config_list_value = unsafe extern "C" fn(config_list: *mut notmuch_config_list_t) -> *const ::std::os::raw::c_char; /// move 'config_list' iterator to the next pair /// +/// ```text /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_config_list_move_to_next = unsafe extern "C" fn(config_list: *mut notmuch_config_list_t); /// free any resources held by 'config_list' /// +/// ```text /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_config_list_destroy = unsafe extern "C" fn(config_list: *mut notmuch_config_list_t); @@ -1948,7 +2025,9 @@ pub type notmuch_config_list_destroy = /// This object represents a set of options on how a message can be /// added to the index. At the moment it is a featureless stub. /// +/// ```text /// @since libnotmuch 5.1 (notmuch 0.26) +/// ``` pub type notmuch_database_get_default_indexopts = unsafe extern "C" fn(db: *mut notmuch_database_t) -> *mut notmuch_indexopts_t; @@ -1967,7 +2046,9 @@ pub type notmuch_decryption_policy_t = u32; /// message index is adequately protected. DO NOT SET THIS FLAG TO TRUE /// without considering the security of your index. /// +/// ```text /// @since libnotmuch 5.1 (notmuch 0.26) +/// ``` pub type notmuch_indexopts_set_decrypt_policy = unsafe extern "C" fn( indexopts: *mut notmuch_indexopts_t, decrypt_policy: notmuch_decryption_policy_t, @@ -1976,17 +2057,23 @@ pub type notmuch_indexopts_set_decrypt_policy = unsafe extern "C" fn( /// Return whether to decrypt encrypted parts while indexing. /// see notmuch_indexopts_set_decrypt_policy. /// +/// ```text /// @since libnotmuch 5.1 (notmuch 0.26) +/// ``` pub type notmuch_indexopts_get_decrypt_policy = unsafe extern "C" fn(indexopts: *const notmuch_indexopts_t) -> notmuch_decryption_policy_t; /// Destroy a notmuch_indexopts_t object. /// +/// ```text /// @since libnotmuch 5.1 (notmuch 0.26) +/// ``` pub type notmuch_indexopts_destroy = unsafe extern "C" fn(options: *mut notmuch_indexopts_t); /// interrogate the library for compile time features /// +/// ```text /// @since libnotmuch 4.4 (notmuch 0.23) +/// ``` pub type notmuch_built_with = unsafe extern "C" fn(name: *const ::std::os::raw::c_char) -> notmuch_bool_t; diff --git a/melib/src/email.rs b/melib/src/email.rs index 99b074d80..538d8887f 100644 --- a/melib/src/email.rs +++ b/melib/src/email.rs @@ -25,7 +25,7 @@ * # Parsing bytes into an `Envelope` * * An [`Envelope`](Envelope) represents the information you can get from an email's headers and body - * structure. Addresses in `To`, `From` fields etc are parsed into [`Address`](email::address::Address) types. + * structure. Addresses in `To`, `From` fields etc are parsed into [`Address`](crate::email::Address) types. * * ``` * use melib::{Attachment, Envelope}; diff --git a/melib/src/email/parser.rs b/melib/src/email/parser.rs index e4685358f..41794f18c 100644 --- a/melib/src/email/parser.rs +++ b/melib/src/email/parser.rs @@ -444,6 +444,7 @@ pub mod dates { } ///e.g Wed Sep 9 00:27:54 2020 + ///```text ///day-of-week month day time year ///date-time = [ day-of-week "," ] date time [CFWS] ///date = day month year @@ -452,6 +453,7 @@ pub mod dates { ///hour = 2DIGIT / obs-hour ///minute = 2DIGIT / obs-minute ///second = 2DIGIT / obs-second + ///``` pub fn mbox_date_time(input: &[u8]) -> IResult<&[u8], UnixTimestamp> { let orig_input = input; let mut accum: SmallVec<[u8; 32]> = SmallVec::new(); @@ -1227,7 +1229,7 @@ pub mod generic { alt((atext_ascii, utf8_non_ascii))(input) } - ///dot-atom = [CFWS] dot-atom-text [CFWS] + ///`dot-atom = [CFWS] dot-atom-text [CFWS]` pub fn dot_atom(input: &[u8]) -> IResult<&[u8], Cow<'_, [u8]>> { let (input, _) = opt(cfws)(input)?; let (input, ret) = dot_atom_text(input)?; diff --git a/melib/src/smtp.rs b/melib/src/smtp.rs index 204d0c6ad..eb3e335a3 100644 --- a/melib/src/smtp.rs +++ b/melib/src/smtp.rs @@ -25,6 +25,9 @@ /*! * SMTP client support * + * This module implements a client for the SMTP protocol as specified by [RFC 5321 Simple Mail + * Transfer Protocol](https://www.rfc-editor.org/rfc/rfc5321). + * * The connection and methods are `async` and uses the `smol` runtime. *# Example * @@ -195,6 +198,7 @@ pub struct SmtpExtensionSupport { pipelining: bool, #[serde(default = "crate::conf::true_val")] chunking: bool, + /// [RFC 6152: SMTP Service Extension for 8-bit MIME Transport](https://www.rfc-editor.org/rfc/rfc6152) #[serde(default = "crate::conf::true_val")] _8bitmime: bool, //Essentially, the PRDR extension to SMTP allows (but does not require) an SMTP server to diff --git a/src/mailcap.rs b/src/mailcap.rs index 0cc566a3c..c581d26de 100644 --- a/src/mailcap.rs +++ b/src/mailcap.rs @@ -19,8 +19,10 @@ * along with meli. If not, see . */ -/*! Find mailcap entries to execute attachments. - */ +//! # mailcap file - Find mailcap entries to execute attachments. +//! +//! Implements [RFC 1524 A User Agent Configuration Mechanism For Multimedia Mail Format +//! Information](https://www.rfc-editor.org/rfc/inline-errata/rfc1524.html) use crate::state::Context; use crate::types::{create_temp_file, ForkType, UIEvent}; use melib::text_processing::GlobMatch; diff --git a/src/terminal/embed/grid.rs b/src/terminal/embed/grid.rs index 8d924278f..baa63fdb0 100644 --- a/src/terminal/embed/grid.rs +++ b/src/terminal/embed/grid.rs @@ -25,15 +25,6 @@ use melib::error::{MeliError, Result}; use melib::text_processing::wcwidth; use nix::sys::wait::WaitStatus; use nix::sys::wait::{waitpid, WaitPidFlag}; -/** - * `EmbedGrid` manages the terminal grid state of the embed process. - * - * The embed process sends bytes to the master end (see super mod) and interprets them in a state - * machine stored in `State`. Escape codes are translated as changes to the grid, eg changes in a - * cell's colors. - * - * The main process copies the grid whenever the actual terminal is redrawn. - **/ #[derive(Debug)] enum ScreenBuffer { @@ -41,10 +32,17 @@ enum ScreenBuffer { Alternate, } +/// `EmbedGrid` manages the terminal grid state of the embed process. +/// +/// The embed process sends bytes to the master end (see super mod) and interprets them in a state +/// machine stored in `State`. Escape codes are translated as changes to the grid, eg changes in a +/// cell's colors. +/// +/// The main process copies the grid whenever the actual terminal is redrawn. #[derive(Debug)] pub struct EmbedGrid { cursor: (usize, usize), - /// [top;bottom] + /// `[top;bottom]` scroll_region: ScrollRegion, pub alternate_screen: CellBuffer, pub state: State,