duesee
/
meli
forked from meli/meli
1
Fork 0
Code Pull Requests Activity

melib: Replace old-style /*! module doc comments with //!

master
Manos Pitsidianakis 2023-07-01 16:20:59 +03:00
parent f0d88005fb
commit f98e36cee5
Signed by: Manos Pitsidianakis
GPG Key ID: 7729C7707F7E09D0
21 changed files with 130 additions and 144 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

150
melib/src/email.rs
View File

@ -19,82 +19,80 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*!
* Email parsing and composing.
*
* # 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`](crate::email::Address) types.
*
* ```
* use melib::{Attachment, Envelope};
*
* let raw_mail = r#"From: "some name" <some@example.com>
* To: "me" <myself@example.com>
* Cc:
* Subject: =?utf-8?Q?gratuitously_encoded_subject?=
* Message-ID: <h2g7f.z0gy2pgaen5m@example.com>
* MIME-Version: 1.0
* Content-Type: multipart/mixed; charset="utf-8";
* boundary="bzz_bzz__bzz__"
*
* This is a MIME formatted message with attachments. Use a MIME-compliant client to view it properly.
* --bzz_bzz__bzz__
*
* hello world.
* --bzz_bzz__bzz__
* Content-Type: image/gif; name="test_image.gif"; charset="utf-8"
* Content-Disposition: attachment
* Content-Transfer-Encoding: base64
*
* R0lGODdhKAAXAOfZAAABzAADzQAEzgQFtBEAxAAGxBcAxwALvRcFwAAPwBcLugATuQEUuxoNuxYQ
* sxwOvAYVvBsStSAVtx8YsRUcuhwhth4iuCQsyDAwuDc1vTc3uDg4uT85rkc9ukJBvENCvURGukdF
* wUVKt0hLuUxPvVZSvFlYu1hbt2BZuFxdul5joGhqlnNuf3FvlnBvwXJyt3Jxw3N0oXx1gH12gV99
* z317f3N7spFxwHp5wH99gYB+goF/g25+26tziIOBhWqD3oiBjICAuudkjIN+zHeC2n6Bzc1vh4eF
* iYaBw8F0kImHi4KFxYyHmIWIvI2Lj4uIvYaJyY+IuJGMi5iJl4qKxZSMmIuLxpONnpGPk42NvI2M
* 1LKGl46OvZePm5ORlZiQnJqSnpaUmLyJnJuTn5iVmZyUoJGVyZ2VoZSVw5iXoZmWrO18rJiUyp6W
* opuYnKaVnZ+Xo5yZncaMoaCYpJiaqo+Z2Z2annuf5qGZpa2WoJybpZmayZ2Z0KCZypydrZ6dp6Cd
* oZ6a0aGay5ucy5+eqKGeouWMgp+b0qKbzKCfqdqPnp2ezaGgqqOgpKafqrScpp+gz6ajqKujr62j
* qayksKmmq62lsaiosqqorOyWnaqqtKeqzLGptaurta2rr7Kqtq+ssLOrt6+uuLGusuqhfbWtubCv
* ubKvs7GwurOwtPSazbevu+ali7SxtbiwvOykjLOyvLWytuCmqOankrSzvbazuLmyvrW0vre0uba1
* wLi1ury0wLm2u721wbe3wbq3vMC2vLi4wr+3w7m5w8C4xLi6yry6vsG5xbu7xcC6zMK6xry8xry+
* u8O7x729x8C9wb++yMG+wsO+vMK/w8a+y8e/zMnBzcXH18nL2///////////////////////////
* ////////////////////////////////////////////////////////////////////////////
* /////////////////////////////////////////////////////ywAAAAAKAAXAAAI/gBP4Cjh
* IYMLEh0w4EgBgsMLEyFGFBEB5cOFABgzatS4AVssZAOsLOHCxooVMzCyoNmzaBOkJlS0VEDyZMjG
* mxk3XOMF60CDBgsoPABK9KcDCRImPCiQYAECAgQCRMU4VSrGCjFarBgUSJCgQ10FBTrkNRCfPnz4
* dA3UNa1btnDZqgU7Ntqzu3ej2X2mFy9eaHuhNRtMGJrhwYYN930G2K7eaNIY34U2mfJkwpgzI9Yr
* GBqwR2KSvAlMOXHnw5pTNzPdLNoWIWtU9XjGjDEYS8LAlFm1SrVvzIKj5TH0KpORSZOryPgCZgqL
* Ob+jG0YVRBErUrOiiGJ8KxgtYsh27xWL/tswnTtEbsiRVYdJNMHk4yOGhswGjR88UKjQ9Ey+/8TL
* XKKGGn7Akph/8XX2WDTTcAYfguVt9hhrEPqmzIOJ3VUheb48WJiHG6amC4i+WVJKKCimqGIoYxyj
* WWK8kKjaJ9bA18sxvXjYhourmbbMMrjI+OIn1QymDCVXANGFK4S1gQw0PxozzC+33FLLKUJq9gk1
* gyWDhyNwrMLkYGUEM4wvuLRiCiieXIJJJVlmJskcZ9TZRht1lnFGGmTMkMoonVQSSSOFAGJHHI0w
* ouiijDaaCCGQRgrpH3q4QYYXWDihxBE+7KCDDjnUIEVAADs=
* --bzz_bzz__bzz__--"#;
*
* let envelope = Envelope::from_bytes(raw_mail.as_bytes(), None).expect("Could not parse mail");
* assert_eq!(envelope.subject().as_ref(), "gratuitously encoded subject");
* assert_eq!(
* envelope.message_id_display().as_ref(),
* "<h2g7f.z0gy2pgaen5m@example.com>"
* );
*
* let body = envelope.body_bytes(raw_mail.as_bytes());
* assert_eq!(body.content_type().to_string().as_str(), "multipart/mixed");
*
* let body_text = body.text();
* assert_eq!(body_text.as_str(), "hello world.");
*
* let subattachments: Vec<Attachment> = body.attachments();
* assert_eq!(subattachments.len(), 3);
* assert_eq!(
* subattachments[2].content_type().name().unwrap(),
* "test_image.gif"
* );
* ```
*/
//! Email parsing and composing.
//!
//! # 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`](crate::email::Address) types.
//!
//! ```
//! use melib::{Attachment, Envelope};
//!
//! let raw_mail = r#"From: "some name" <some@example.com>
//! To: "me" <myself@example.com>
//! Cc:
//! Subject: =?utf-8?Q?gratuitously_encoded_subject?=
//! Message-ID: <h2g7f.z0gy2pgaen5m@example.com>
//! MIME-Version: 1.0
//! Content-Type: multipart/mixed; charset="utf-8";
//! boundary="bzz_bzz__bzz__"
//!
//! This is a MIME formatted message with attachments. Use a MIME-compliant client to view it properly.
//! --bzz_bzz__bzz__
//!
//! hello world.
//! --bzz_bzz__bzz__
//! Content-Type: image/gif; name="test_image.gif"; charset="utf-8"
//! Content-Disposition: attachment
//! Content-Transfer-Encoding: base64
//!
//! R0lGODdhKAAXAOfZAAABzAADzQAEzgQFtBEAxAAGxBcAxwALvRcFwAAPwBcLugATuQEUuxoNuxYQ
//! sxwOvAYVvBsStSAVtx8YsRUcuhwhth4iuCQsyDAwuDc1vTc3uDg4uT85rkc9ukJBvENCvURGukdF
//! wUVKt0hLuUxPvVZSvFlYu1hbt2BZuFxdul5joGhqlnNuf3FvlnBvwXJyt3Jxw3N0oXx1gH12gV99
//! z317f3N7spFxwHp5wH99gYB+goF/g25+26tziIOBhWqD3oiBjICAuudkjIN+zHeC2n6Bzc1vh4eF
//! iYaBw8F0kImHi4KFxYyHmIWIvI2Lj4uIvYaJyY+IuJGMi5iJl4qKxZSMmIuLxpONnpGPk42NvI2M
//! 1LKGl46OvZePm5ORlZiQnJqSnpaUmLyJnJuTn5iVmZyUoJGVyZ2VoZSVw5iXoZmWrO18rJiUyp6W
//! opuYnKaVnZ+Xo5yZncaMoaCYpJiaqo+Z2Z2annuf5qGZpa2WoJybpZmayZ2Z0KCZypydrZ6dp6Cd
//! oZ6a0aGay5ucy5+eqKGeouWMgp+b0qKbzKCfqdqPnp2ezaGgqqOgpKafqrScpp+gz6ajqKujr62j
//! qayksKmmq62lsaiosqqorOyWnaqqtKeqzLGptaurta2rr7Kqtq+ssLOrt6+uuLGusuqhfbWtubCv
//! ubKvs7GwurOwtPSazbevu+ali7SxtbiwvOykjLOyvLWytuCmqOankrSzvbazuLmyvrW0vre0uba1
//! wLi1ury0wLm2u721wbe3wbq3vMC2vLi4wr+3w7m5w8C4xLi6yry6vsG5xbu7xcC6zMK6xry8xry+
//! u8O7x729x8C9wb++yMG+wsO+vMK/w8a+y8e/zMnBzcXH18nL2///////////////////////////
//! ////////////////////////////////////////////////////////////////////////////
//! /////////////////////////////////////////////////////ywAAAAAKAAXAAAI/gBP4Cjh
//! IYMLEh0w4EgBgsMLEyFGFBEB5cOFABgzatS4AVssZAOsLOHCxooVMzCyoNmzaBOkJlS0VEDyZMjG
//! mxk3XOMF60CDBgsoPABK9KcDCRImPCiQYAECAgQCRMU4VSrGCjFarBgUSJCgQ10FBTrkNRCfPnz4
//! dA3UNa1btnDZqgU7Ntqzu3ej2X2mFy9eaHuhNRtMGJrhwYYN930G2K7eaNIY34U2mfJkwpgzI9Yr
//! GBqwR2KSvAlMOXHnw5pTNzPdLNoWIWtU9XjGjDEYS8LAlFm1SrVvzIKj5TH0KpORSZOryPgCZgqL
//! Ob+jG0YVRBErUrOiiGJ8KxgtYsh27xWL/tswnTtEbsiRVYdJNMHk4yOGhswGjR88UKjQ9Ey+/8TL
//! XKKGGn7Akph/8XX2WDTTcAYfguVt9hhrEPqmzIOJ3VUheb48WJiHG6amC4i+WVJKKCimqGIoYxyj
//! WWK8kKjaJ9bA18sxvXjYhourmbbMMrjI+OIn1QymDCVXANGFK4S1gQw0PxozzC+33FLLKUJq9gk1
//! gyWDhyNwrMLkYGUEM4wvuLRiCiieXIJJJVlmJskcZ9TZRht1lnFGGmTMkMoonVQSSSOFAGJHHI0w
//! ouiijDaaCCGQRgrpH3q4QYYXWDihxBE+7KCDDjnUIEVAADs=
//! --bzz_bzz__bzz__--"#;
//!
//! let envelope = Envelope::from_bytes(raw_mail.as_bytes(), None).expect("Could not parse mail");
//! assert_eq!(envelope.subject().as_ref(), "gratuitously encoded subject");
//! assert_eq!(
//! envelope.message_id_display().as_ref(),
//! "<h2g7f.z0gy2pgaen5m@example.com>"
//! );
//!
//! let body = envelope.body_bytes(raw_mail.as_bytes());
//! assert_eq!(body.content_type().to_string().as_str(), "multipart/mixed");
//!
//! let body_text = body.text();
//! assert_eq!(body_text.as_str(), "hello world.");
//!
//! let subattachments: Vec<Attachment> = body.attachments();
//! assert_eq!(subattachments.len(), 3);
//! assert_eq!(
//! subattachments[2].content_type().name().unwrap(),
//! "test_image.gif"
//! );
//! ```
pub mod address;
pub mod attachment_types;

4
melib/src/email/compose.rs
View File

@ -19,7 +19,7 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*! Compose a `Draft`, with MIME and attachment support */
//! Compose a [``Draft`], with `MIME` and attachment support.
use std::{
convert::TryFrom,
ffi::OsStr,
@ -43,8 +43,6 @@ use crate::{
pub mod mime;
pub mod random;
//use self::mime::*;
use super::parser;
#[derive(Debug, PartialEq, Eq, Clone)]

2
melib/src/email/headers.rs
View File

@ -19,7 +19,7 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*! Wrapper type `HeaderName` for case-insensitive comparisons */
//! Wrapper type [`HeaderName`] for case-insensitive comparisons.
pub mod names;
use std::{

2
melib/src/email/headers/names.rs
View File

@ -19,7 +19,7 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*! E-mail header names. Also referred to as Fields in [RFC5322] */
//! E-mail header names. Also referred to as `Fields` in `RFC5322`.
#![allow(non_upper_case_globals)]
use std::{

3
melib/src/email/list_management.rs
View File

@ -19,7 +19,8 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*! Parsing of rfc2369/rfc2919 `List-*` headers */
//! Parsing of `RFC2369` and `RFC2919` `List-*` headers.
use std::convert::From;
use smallvec::SmallVec;

16
melib/src/email/parser.rs
View File

@ -327,7 +327,7 @@ pub fn mail(input: &[u8]) -> Result<(Vec<(&[u8], &[u8])>, &[u8])> {
}
pub mod dates {
/*! Date values in headers */
//! Date values in headers.
use super::{generic::*, *};
use crate::utils::datetime::UnixTimestamp;
@ -634,7 +634,7 @@ pub mod dates {
}
pub mod generic {
/*! Generally useful parser combinators */
//! Generally useful parser combinators.
use super::*;
#[inline(always)]
pub fn byte_in_slice<'a>(slice: &'static [u8]) -> impl Fn(&'a [u8]) -> IResult<&'a [u8], u8> {
@ -664,9 +664,9 @@ pub mod generic {
}
}
///UTF-8 characters can be defined in terms of octets using the
///following ABNF [RFC5234], taken from [RFC3629]:
///UTF8-non-ascii = UTF8-2 / UTF8-3 / UTF8-4
/// UTF-8 characters can be defined in terms of octets using the
/// following ABNF `[RFC5234]`, taken from `[RFC3629]`:
/// UTF8-non-ascii = UTF8-2 / UTF8-3 / UTF8-4
fn utf8_non_ascii(input: &[u8]) -> IResult<&[u8], Cow<'_, [u8]>> {
/// UTF8-2 = %xC2-DF UTF8-tail
fn utf8_2(input: &[u8]) -> IResult<&[u8], &[u8]> {
@ -1414,7 +1414,7 @@ List-Archive: <http://www.host.com/list/archive/> (Web Archive)
}
pub mod headers {
/*! Email headers */
//! Email headers.
use super::*;
pub fn headers(input: &[u8]) -> IResult<&[u8], Vec<(&[u8], &[u8])>> {
@ -1675,7 +1675,7 @@ pub mod headers {
}
pub mod attachments {
/*! Email attachments */
//! Email attachments.
use super::*;
use crate::email::{
address::*,
@ -1945,7 +1945,7 @@ pub mod attachments {
}
pub mod encodings {
/*! Email encodings (quoted printable, MIME) */
//! Email encodings (quoted printable, `MIME`).
use data_encoding::BASE64_MIME;
use encoding::{all::*, DecoderTrap, Encoding};

7
melib/src/email/pgp.rs
View File

@ -19,7 +19,7 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*! Verification of OpenPGP signatures */
//! Verification of OpenPGP signatures.
use crate::{
email::{
attachment_types::{ContentType, MultipartType},
@ -28,9 +28,10 @@ use crate::{
Error, Result,
};
/// Convert raw attachment to the form needed for signature verification ([rfc3156](https://tools.ietf.org/html/rfc3156))
/// Convert raw attachment to the form needed for signature verification ([RFC3156](https://tools.ietf.org/html/rfc3156))
///
/// ## RFC3156
///
/// ## rfc3156
/// ```text
/// Upon receipt of a signed message, an application MUST:
///

4
melib/src/error.rs
View File

@ -19,9 +19,7 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*!
* An error object for `melib`
*/
//! Library error type.
use std::{borrow::Cow, fmt, io, result, str, string, sync::Arc};

2
melib/src/sieve.rs
View File

@ -142,7 +142,7 @@ pub enum ZoneRule {
/// "iso8601" => the date and time in restricted ISO 8601 format.
Iso8601,
/// "std11" => the date and time in a format appropriate
/// for use in a Date: header field [RFC2822].
/// for use in a Date: header field (`RFC2822`).
Std11,
/// "zone" => the time zone in use. If the user specified a
///time zone with ":zone", "zone" will

7
melib/src/text_processing/line_break.rs
View File

@ -1270,10 +1270,9 @@ easy to take MORE than nothing.'"#;
}
mod segment_tree {
/*! Simple segment tree implementation for maximum in range queries. This
* is useful if given an array of numbers you want to get the
* maximum value inside an interval quickly.
*/
//! Simple segment tree implementation for maximum in range queries. This
//! is useful if given an array of numbers you want to get the
//! maximum value inside an interval quickly.
use std::{convert::TryFrom, iter::FromIterator};
use smallvec::SmallVec;

26
melib/src/thread.rs
View File

@ -19,19 +19,19 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*!
* e-mail threading (conversations)
*
* This module implements Jamie Zawinski's [threading algorithm](https://www.jwz.org/doc/threading.html). Quoted comments (/* " .. " */) are
* taken almost verbatim from the algorithm.
*
* The entry point of this module is the `Threads` struct and its `new`
* method. It contains `ThreadNodes` which are the nodes in the thread trees
* that might have messages associated with them. The root nodes (first
* messages in each thread) are stored in `root_set` and `tree`
* vectors. `Threads` has inner mutability since we need to sort without the
* user having mutable ownership.
*/
//! e-mail threading (conversations)
//!
//! This module implements Jamie Zawinski's [threading
//! algorithm](https://www.jwz.org/doc/threading.html). Quoted comments (/* " .. " */) are taken
//! almost verbatim from the algorithm.
//!
//! The entry point of this module is the [`Threads`] struct and its
//! [`new`](Threads::new) method. It contains [`ThreadNode`s](ThreadNode) which
//! are the nodes in the thread trees that might have messages associated with
//! them. The root nodes (first messages in each thread) are stored in
//! [`root_set`](Threads::root_set) and [`thread_nodes`](Threads::thread_nodes)
//! vectors. [`Threads`] has inner mutability since we need to sort without the
//! user having mutable ownership.
use crate::{
email::{address::StrBuild, parser::BytesExt, *},

5
src/command.rs
View File

@ -19,8 +19,9 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*! A parser module for user commands passed through Command mode.
*/
//! A parser module for user commands passed through
//! [`Command`](crate::types::UIMode::Command) mode.
pub use melib::thread::{SortField, SortOrder};
use melib::{
nom::{

14
src/components.rs
View File

@ -19,14 +19,12 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*! Components visual and logical separations of application interfaces.
*
* They can draw on the terminal and receive events, but also do other stuff
* as well.
* For an example, see the [`notifications`] module.
* See also the [`Component`] trait for more details.
*/
//! Components visual and logical separations of application interfaces.
///
/// They can draw on the terminal and receive events, but also do other stuff
/// as well.
/// For an example, see the [`notifications`] module.
/// See also the [`Component`] trait for more details.
use smallvec::SmallVec;
use super::*;

3
src/components/utilities.rs
View File

@ -19,8 +19,7 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*! Various useful components that can be used in a generic fashion.
*/
//! Various useful utilities.
use melib::{text_processing::Reflow, ShellExpandTrait};

2
src/components/utilities/tables.rs
View File

@ -19,7 +19,7 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*! UI components to display tabular lists. */
//! UI components to display tabular lists.
use std::mem::MaybeUninit;
use super::*;

2
src/conf.rs
View File

@ -19,7 +19,7 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*! Configuration logic and `config.toml` interfaces. */
//! Configuration logic and `config.toml` interfaces.
extern crate serde;
extern crate toml;

4
src/conf/accounts.rs
View File

@ -19,9 +19,7 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*!
* Account management from user configuration.
*/
//! Account management from user configuration.
use std::{
borrow::Cow,

4
src/plugins.rs
View File

@ -19,8 +19,8 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*! Plugins are executed by meli and communication is done by `messagepack` IPC.
*/
//! Plugins are executed by meli and communication is done by `messagepack` IPC.
use melib::error::{Error, Result};
use std::collections::HashMap;
use std::io::Write;

3
src/sqlite3.rs
View File

@ -19,8 +19,7 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*! Use an sqlite3 database for fast searching.
*/
//! Use an sqlite3 database for fast searching.
use std::{
path::PathBuf,
sync::{Arc, RwLock},

6
src/terminal/cells.rs
View File

@ -19,10 +19,8 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*!
Define a (x, y) point in the terminal display as a holder of a character, foreground/background
colors and attributes.
*/
//! Define a `(x, y)` point in the terminal display as a holder of a character,
//! foreground/background colors and attributes.
use std::{
collections::HashMap,

8
src/terminal/position.rs
View File

@ -19,11 +19,9 @@
* along with meli. If not, see <http://www.gnu.org/licenses/>.
*/
/*!
Simple type definitions and macro helper for a (x,y) position on the terminal and the areas they define.
An `Area` consists of two points: the upper left and bottom right corners.
*/
//! Simple type definitions and macro helper for a `(x, y)` position on the
//! terminal and the areas they define. An [`Area`] consists of two points: the
//! upper left and bottom right corners.
/// A `(x, y)` position on screen.
pub type Pos = (usize, usize);