From 27a4dcb916e0bed723490df9d82bfd7c83f10a83 Mon Sep 17 00:00:00 2001 From: Manos Pitsidianakis Date: Sun, 4 Jun 2023 21:07:26 +0300 Subject: [PATCH] Fix some rustdoc lints --- melib/src/email/parser.rs | 81 +++++++++++++++------------- melib/src/smtp.rs | 30 +++++------ melib/src/utils/datetime.rs | 4 +- src/components/mail.rs | 4 +- src/components/mail/compose/hooks.rs | 4 +- src/conf/composing.rs | 3 +- src/state.rs | 22 ++++---- src/terminal/keys.rs | 4 +- 8 files changed, 83 insertions(+), 69 deletions(-) diff --git a/melib/src/email/parser.rs b/melib/src/email/parser.rs index 905ad1d59..2d68350b8 100644 --- a/melib/src/email/parser.rs +++ b/melib/src/email/parser.rs @@ -344,15 +344,15 @@ pub mod dates { } } - ///In the obsolete time zone, "UT" and "GMT" are indications of - ///"Universal Time" and "Greenwich Mean Time", respectively, and are - ///both semantically identical to "+0000". + /// In the obsolete time zone, "UT" and "GMT" are indications of + /// "Universal Time" and "Greenwich Mean Time", respectively, and are + /// both semantically identical to "+0000". - ///The remaining three character zones are the US time zones. The first - ///letter, "E", "C", "M", or "P" stands for "Eastern", "Central", - ///"Mountain", and "Pacific". The second letter is either "S" for - ///"Standard" time, or "D" for "Daylight Savings" (or summer) time. - ///Their interpretations are as follows: + /// The remaining three character zones are the US time zones. The first + /// letter, "E", "C", "M", or "P" stands for "Eastern", "Central", + /// "Mountain", and "Pacific". The second letter is either "S" for + /// "Standard" time, or "D" for "Daylight Savings" (or summer) time. + /// Their interpretations are as follows: /// EDT is semantically equivalent to -0400 /// EST is semantically equivalent to -0500 @@ -363,21 +363,21 @@ pub mod dates { /// PDT is semantically equivalent to -0700 /// PST is semantically equivalent to -0800 - ///The 1 character military time zones were defined in a non-standard - ///way in [RFC0822] and are therefore unpredictable in their meaning. - ///The original definitions of the military zones "A" through "I" are - ///equivalent to "+0100" through "+0900", respectively; "K", "L", and - ///"M" are equivalent to "+1000", "+1100", and "+1200", respectively; - ///"N" through "Y" are equivalent to "-0100" through "-1200". - ///respectively; and "Z" is equivalent to "+0000". However, because of - ///the error in [RFC0822], they SHOULD all be considered equivalent to - ///"-0000" unless there is out-of-band information confirming their - ///meaning. + /// The 1 character military time zones were defined in a non-standard + /// way in RFC0822 and are therefore unpredictable in their meaning. + /// The original definitions of the military zones "A" through "I" are + /// equivalent to "+0100" through "+0900", respectively; "K", "L", and + /// "M" are equivalent to "+1000", "+1100", and "+1200", respectively; + /// "N" through "Y" are equivalent to "-0100" through "-1200". + /// respectively; and "Z" is equivalent to "+0000". However, because of + /// the error in RFC0822, they SHOULD all be considered equivalent to + /// "-0000" unless there is out-of-band information confirming their + /// meaning. - ///Other multi-character (usually between 3 and 5) alphabetic time zones - ///have been used in Internet messages. Any such time zone whose - ///meaning is not known SHOULD be considered equivalent to "-0000" - ///unless there is out-of-band information confirming their meaning. + /// Other multi-character (usually between 3 and 5) alphabetic time zones + /// have been used in Internet messages. Any such time zone whose + /// meaning is not known SHOULD be considered equivalent to "-0000" + /// unless there is out-of-band information confirming their meaning. fn obs_zone(input: &[u8]) -> IResult<&[u8], (&[u8], &[u8])> { alt(( map(tag("UT"), |_| (&b"+"[..], &b"0000"[..])), @@ -394,7 +394,9 @@ pub mod dates { ))(input) } - ///zone = (FWS ( "+" / "-" ) 4DIGIT) / obs-zone + /// ```text + /// zone = (FWS ( "+" / "-" ) 4DIGIT) / obs-zone + /// ``` fn zone(input: &[u8]) -> IResult<&[u8], (&[u8], &[u8])> { alt(( |input| { @@ -406,13 +408,15 @@ pub mod dates { ))(input) } - ///date-time = [ day-of-week "," ] date time [CFWS] - ///date = day month year - ///time = time-of-day zone - ///time-of-day = hour ":" minute [ ":" second ] - ///hour = 2DIGIT / obs-hour - ///minute = 2DIGIT / obs-minute - ///second = 2DIGIT / obs-second + /// ```text + /// date-time = [ day-of-week "," ] date time [CFWS] + /// date = day month year + /// time = time-of-day zone + /// time-of-day = hour ":" minute [ ":" second ] + /// hour = 2DIGIT / obs-hour + /// minute = 2DIGIT / obs-minute + /// second = 2DIGIT / obs-second + /// ``` fn date_time(input: &[u8]) -> IResult<&[u8], UnixTimestamp> { let orig_input = input; let mut accum: SmallVec<[u8; 32]> = SmallVec::new(); @@ -459,8 +463,9 @@ pub mod dates { } } - ///e.g Wed Sep 9 00:27:54 2020 - ///```text + /// 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 @@ -520,9 +525,11 @@ pub mod dates { } } - ///`day-of-week = ([FWS] day-name) / obs-day-of-week` - ///day-name = "Mon" / "Tue" / "Wed" / "Thu" / + /// ```text + /// day-of-week = ([FWS] day-name) / obs-day-of-week + /// day-name = "Mon" / "Tue" / "Wed" / "Thu" / /// "Fri" / "Sat" / "Sun" + /// ``` fn day_of_week(input: &[u8]) -> IResult<&[u8], Cow<'_, [u8]>> { let (input, day_name) = alt(( tag("Mon"), @@ -536,7 +543,7 @@ pub mod dates { Ok((input, day_name.into())) } - ///day = ([FWS] 1*2DIGIT FWS) / obs-day + /// `day = ([FWS] 1*2DIGIT FWS) / obs-day` fn day(input: &[u8]) -> IResult<&[u8], &[u8]> { let (input, _) = opt(fws)(input)?; let (input, ret) = alt((take_n_digits(2), take_n_digits(1)))(input)?; @@ -545,9 +552,11 @@ pub mod dates { Ok((input, ret)) } - ///month = "Jan" / "Feb" / "Mar" / "Apr" / + /// ```text + /// month = "Jan" / "Feb" / "Mar" / "Apr" / /// "May" / "Jun" / "Jul" / "Aug" / /// "Sep" / "Oct" / "Nov" / "Dec" + /// ``` fn month(input: &[u8]) -> IResult<&[u8], &[u8]> { alt(( tag("Jan"), diff --git a/melib/src/smtp.rs b/melib/src/smtp.rs index 8f9d1f3b3..5cdb83b4d 100644 --- a/melib/src/smtp.rs +++ b/melib/src/smtp.rs @@ -202,7 +202,7 @@ pub struct SmtpExtensionSupport { #[serde(default = "crate::conf::true_val")] binarymime: bool, /// Resources: - /// - http://www.postfix.org/SMTPUTF8_README.html + /// - #[serde(default = "crate::conf::true_val")] smtputf8: bool, #[serde(default = "crate::conf::true_val")] @@ -608,7 +608,7 @@ impl SmtpConnection { } let mut current_command: SmallVec<[&[u8]; 16]> = SmallVec::new(); //first step in the procedure is the MAIL command. - // MAIL FROM: [SP ] + // `MAIL FROM: [SP ] ` current_command.push(b"MAIL FROM:<"); if !envelope_from.is_empty() { current_command.push(envelope_from.trim().as_bytes()); @@ -668,8 +668,8 @@ impl SmtpConnection { } self.send_command(¤t_command).await?; - //RCPT TO: [ SP ] - //If accepted, the SMTP server returns a "250 OK" reply and stores the + //`RCPT TO: [ SP ] ` + // If accepted, the SMTP server returns a "250 OK" reply and stores the // forward-path. if !self.server_conf.extensions.pipelining { self.read_lines(&mut res, Some((ReplyCode::_250, &[]))) @@ -679,7 +679,7 @@ impl SmtpConnection { } } - //Since it has been a common source of errors, it is worth noting that spaces + // Since it has been a common source of errors, it is worth noting that spaces // are not permitted on either side of the colon following FROM in the // MAIL command or TO in the RCPT command. The syntax is exactly as // given above. @@ -692,7 +692,7 @@ impl SmtpConnection { } else { //The third step in the procedure is the DATA command //(or some alternative specified in a service extension). - //DATA + //DATA `` self.send_command(&[b"DATA"]).await?; //Client SMTP implementations that employ pipelining MUST check ALL statuses // associated with each command in a group. For example, if none of @@ -739,7 +739,7 @@ impl SmtpConnection { } //The mail data are terminated by a line containing only a period, that is, the - // character sequence ".", where the first is + // character sequence "``.``", where the first `` is // actually the terminator of the previous line (see Section 4.5.2). // This is the end of mail data indication. self.stream.write_all(b".\r\n").await?; @@ -788,15 +788,15 @@ pub enum ReplyCode { /// particular non-standard command; this reply is useful only to the human /// user) _214, - /// Service ready + /// `` Service ready _220, - /// Service closing transmission channel + /// `` Service closing transmission channel _221, /// Authentication successful, _235, /// Requested mail action okay, completed _250, - /// User not local; will forward to (See Section 3.4) + /// User not local; will forward to `` (See Section 3.4) _251, /// Cannot VRFY user, but will accept message and attempt delivery (See /// Section 3.5.3) @@ -805,9 +805,9 @@ pub enum ReplyCode { _334, /// PRDR specific, eg "content analysis has started| _353, - /// Start mail input; end with . + /// Start mail input; end with ``.`` _354, - /// Service not available, closing transmission channel (This may + /// `` Service not available, closing transmission channel (This may /// be a reply to any command if the service knows it must shut down) _421, /// Requested mail action not taken: mailbox unavailable (e.g., mailbox busy @@ -835,7 +835,7 @@ pub enum ReplyCode { /// Requested action not taken: mailbox unavailable (e.g., mailbox not /// found, no access, or command rejected for policy reasons) _550, - /// User not local; please try (See Section 3.4) + /// User not local; please try `` (See Section 3.4) _551, /// Requested mail action aborted: exceeded storage allocation _552, @@ -998,8 +998,8 @@ async fn read_lines<'r>( let mut returned_code: Option = None; 'read_loop: loop { while let Some(pos) = ret[last_line_idx..].find("\r\n") { - // "Formally, a reply is defined to be the sequence: a three-digit code, , - // one line of text, and , or a multiline reply (as defined in the same + // "Formally, a reply is defined to be the sequence: a three-digit code, ``, + // one line of text, and ``, or a multiline reply (as defined in the same // section)." if ret[last_line_idx..].len() < 4 || !ret[last_line_idx..] diff --git a/melib/src/utils/datetime.rs b/melib/src/utils/datetime.rs index 8fc1d79fd..2ae1b401c 100644 --- a/melib/src/utils/datetime.rs +++ b/melib/src/utils/datetime.rs @@ -49,9 +49,9 @@ use crate::error::{Result, ResultIntoError}; pub type UnixTimestamp = u64; pub mod formats { - /// T