Rust documentation improvements

Document all public modules and some methods.

Make some internal public symbols private.

src/accounts.rs

@@ -1,3 +1,5 @@
+//! # Account manager module.
+
 use std::collections::BTreeMap;
 
 use async_std::channel::{Receiver, Sender};
@@ -251,12 +253,13 @@ impl Accounts {
         }
     }
 
-    /// Unified event emitter.
+    /// Returns unified event emitter.
     pub async fn get_event_emitter(&self) -> EventEmitter {
         self.emitter.clone()
     }
 }
 
+/// Unified event emitter for multiple accounts.
 #[derive(Debug, Clone)]
 pub struct EventEmitter {
     /// Aggregate stream of events from all accounts.
@@ -324,6 +327,7 @@ impl async_std::stream::Stream for EventEmitter {
 pub const CONFIG_NAME: &str = "accounts.toml";
 pub const DB_NAME: &str = "dc.db";
 
+/// Account manager configuration file.
 #[derive(Debug, Clone)]
 pub struct Config {
     file: PathBuf,
@@ -398,7 +402,7 @@ impl Config {
     }
 
     /// Create a new account in the given root directory.
-    pub async fn new_account(&self, dir: &PathBuf) -> Result<AccountConfig> {
+    async fn new_account(&self, dir: &PathBuf) -> Result<AccountConfig> {
         let id = {
             let inner = &mut self.inner.write().await;
             let id = inner.next_id;
@@ -438,7 +442,7 @@ impl Config {
         self.sync().await
     }
 
-    pub async fn get_account(&self, id: u32) -> Option<AccountConfig> {
+    async fn get_account(&self, id: u32) -> Option<AccountConfig> {
         self.inner
             .read()
             .await
@@ -469,8 +473,9 @@ impl Config {
     }
 }
 
+/// Configuration of a single account.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
-pub struct AccountConfig {
+struct AccountConfig {
     /// Unique id.
     pub id: u32,
     /// Root directory for all data for this account.

src/aheader.rs

@@ -1,4 +1,4 @@
-//! # Autocrypt header module
+//! # Autocrypt header module.
 //!
 //! Parse and create [Autocrypt-headers](https://autocrypt.org/en/latest/level1.html#the-autocrypt-header).
 

src/blob.rs

@@ -1,4 +1,4 @@
-//! # Blob directory management
+//! # Blob directory management.
 
 use core::cmp::max;
 use std::ffi::OsStr;

src/chat.rs

@@ -1,4 +1,4 @@
-//! # Chat module
+//! # Chat module.
 
 use std::convert::{TryFrom, TryInto};
 use std::str::FromStr;
@@ -975,6 +975,7 @@ impl Chat {
         &self.name
     }
 
+    /// Returns profile image path for the chat.
     pub async fn get_profile_image(&self, context: &Context) -> Result<Option<PathBuf>> {
         if let Some(image_rel) = self.param.get(Param::ProfileImage) {
             if !image_rel.is_empty() {
@@ -1989,6 +1990,7 @@ pub(crate) async fn marknoticed_chat_if_older_than(
     Ok(())
 }
 
+/// Marks all messages in the chat as noticed.
 pub async fn marknoticed_chat(context: &Context, chat_id: ChatId) -> Result<()> {
     // "WHERE" below uses the index `(state, hidden, chat_id)`, see get_fresh_msg_cnt() for reasoning
     // the additional SELECT statement may speed up things as no write-blocking is needed.
@@ -2109,6 +2111,7 @@ pub async fn get_next_media(
     Ok(ret)
 }
 
+/// Returns a vector of contact IDs for given chat ID.
 pub async fn get_chat_contacts(context: &Context, chat_id: ChatId) -> Result<Vec<u32>> {
     // Normal chats do not include SELF.  Group chats do (as it may happen that one is deleted from a
     // groupchat but the chats stays visible, moreover, this makes displaying lists easier)
@@ -2131,6 +2134,7 @@ pub async fn get_chat_contacts(context: &Context, chat_id: ChatId) -> Result<Vec
     Ok(list)
 }
 
+/// Creates a group chat with a given `name`.
 pub async fn create_group_chat(
     context: &Context,
     protect: ProtectionStatus,
@@ -2178,7 +2182,7 @@ pub async fn create_group_chat(
     Ok(chat_id)
 }
 
-/// add a contact to the chats_contact table
+/// Adds a contact to the `chats_contacts` table.
 pub(crate) async fn add_to_chat_contacts_table(
     context: &Context,
     chat_id: ChatId,
@@ -2566,6 +2570,7 @@ pub(crate) async fn is_group_explicitly_left(
     Ok(exists)
 }
 
+/// Sets group or mailing list chat name.
 pub async fn set_chat_name(context: &Context, chat_id: ChatId, new_name: &str) -> Result<()> {
     let new_name = improve_single_line_input(new_name);
     /* the function only sets the names of group chats; normal chats get their names from the contacts */
@@ -2939,6 +2944,7 @@ pub async fn add_device_msg_with_importance(
     Ok(msg_id)
 }
 
+/// Adds a message to device chat.
 pub async fn add_device_msg(
     context: &Context,
     label: Option<&str>,

src/chatlist.rs

@@ -1,4 +1,4 @@
-//! # Chat list module
+//! # Chat list module.
 
 use anyhow::{bail, ensure, Result};
 

src/color.rs

@@ -1,4 +1,4 @@
-//! Implementation of Consistent Color Generation
+//! Implementation of Consistent Color Generation.
 //!
 //! Consistent Color Generation is defined in XEP-0392.
 //!

src/config.rs

@@ -1,4 +1,4 @@
-//! # Key-value configuration management
+//! # Key-value configuration management.
 
 use anyhow::Result;
 use strum::{EnumProperty, IntoEnumIterator};

src/configure.rs

@@ -1,4 +1,4 @@
-//! Email accounts autoconfiguration process module
+//! Email accounts autoconfiguration process module.
 
 mod auto_mozilla;
 mod auto_outlook;

src/constants.rs

@@ -1,4 +1,4 @@
-//! # Constants
+//! # Constants.
 use deltachat_derive::{FromSql, ToSql};
 use once_cell::sync::Lazy;
 use serde::{Deserialize, Serialize};

src/context.rs

@@ -1,4 +1,4 @@
-//! Context module
+//! Context module.
 
 use std::collections::{BTreeMap, HashMap};
 use std::ffi::OsString;

src/dc_receive_imf.rs

@@ -1,3 +1,5 @@
+//! Internet Message Format reception pipeline.
+
 use std::convert::TryFrom;
 
 use anyhow::{bail, ensure, format_err, Result};

src/dehtml.rs

@@ -1,4 +1,4 @@
-//! De-HTML
+//! De-HTML.
 //!
 //! A module to remove HTML tags from the email text
 

src/e2ee.rs

@@ -335,7 +335,7 @@ fn has_decrypted_pgp_armor(input: &[u8]) -> bool {
     false
 }
 
-/// Check if a MIME structure contains a multipart/report part.
+/// Checks if a MIME structure contains a multipart/report part.
 ///
 /// As reports are often unencrypted, we do not reset the Autocrypt header in
 /// this case.

src/ephemeral.rs

@@ -1,4 +1,4 @@
-//! # Ephemeral messages
+//! # Ephemeral messages.
 //!
 //! Ephemeral messages are messages that have an Ephemeral-Timer
 //! header attached to them, which specifies time in seconds after

src/events.rs

@@ -1,4 +1,4 @@
-//! # Events specification
+//! # Events specification.
 
 use std::ops::Deref;
 

src/format_flowed.rs

@@ -1,13 +1,13 @@
-///! # format=flowed support
-///!
-///! Format=flowed is defined in
-///! [RFC 3676](https://tools.ietf.org/html/rfc3676).
-///!
-///! Older [RFC 2646](https://tools.ietf.org/html/rfc2646) is used
-///! during formatting, i.e., DelSp parameter introduced in RFC 3676
-///! is assumed to be set to "no".
-///!
-///! For received messages, DelSp parameter is honoured.
+//! # format=flowed support.
+//!
+//! Format=flowed is defined in
+//! [RFC 3676](https://tools.ietf.org/html/rfc3676).
+//!
+//! Older [RFC 2646](https://tools.ietf.org/html/rfc2646) is used
+//! during formatting, i.e., DelSp parameter introduced in RFC 3676
+//! is assumed to be set to "no".
+//!
+//! For received messages, DelSp parameter is honoured.
 
 /// Wraps line to 72 characters using format=flowed soft breaks.
 ///

src/headerdef.rs

@@ -1,3 +1,5 @@
+//! # List of email headers.
+
 use crate::strum::AsStaticRef;
 use mailparse::{MailHeader, MailHeaderMap};
 

src/html.rs

@@ -1,11 +1,12 @@
-///! # Get message as HTML.
-///!
-///! Use `Message.has_html()` to check if the UI shall render a
-///! corresponding button and `MsgId.get_html()` to get the full message.
-///!
-///! Even when the original mime-message is not HTML,
-///! `MsgId.get_html()` will return HTML -
-///! this allows nice quoting, handling linebreaks properly etc.
+//! # Get message as HTML.
+//!
+//! Use `Message.has_html()` to check if the UI shall render a
+//! corresponding button and `MsgId.get_html()` to get the full message.
+//!
+//! Even when the original mime-message is not HTML,
+//! `MsgId.get_html()` will return HTML -
+//! this allows nice quoting, handling linebreaks properly etc.
+
 use futures::future::FutureExt;
 use std::future::Future;
 use std::pin::Pin;

src/imap.rs

@@ -1,4 +1,4 @@
-//! # Imap handling module
+//! # IMAP handling module.
 //!
 //! uses [async-email/async-imap](https://github.com/async-email/async-imap)
 //! to implement connect, fetch, delete functionality with standard IMAP servers.

src/imex.rs

@@ -1,4 +1,4 @@
-//! # Import/export module
+//! # Import/export module.
 
 use std::any::Any;
 use std::ffi::OsStr;
@@ -66,15 +66,15 @@ pub enum ImexMode {
 
 /// Import/export things.
 ///
-/// What to do is defined by the *what* parameter.
+/// What to do is defined by the `what` parameter.
 ///
 /// During execution of the job,
 /// some events are sent out:
 ///
-/// - A number of #DC_EVENT_IMEX_PROGRESS events are sent and may be used to create
+/// - A number of `DC_EVENT_IMEX_PROGRESS` events are sent and may be used to create
 ///   a progress bar or stuff like that. Moreover, you'll be informed when the imex-job is done.
 ///
-/// - For each file written on export, the function sends #DC_EVENT_IMEX_FILE_WRITTEN
+/// - For each file written on export, the function sends `DC_EVENT_IMEX_FILE_WRITTEN`
 ///
 /// Only one import-/export-progress can run at the same time.
 /// To cancel an import-/export-progress, drop the future returned by this function.
@@ -204,6 +204,7 @@ pub async fn has_backup_old(context: &Context, dir_name: &Path) -> Result<String
     }
 }
 
+/// Initiates key transfer via Autocrypt Setup Message.
 pub async fn initiate_key_transfer(context: &Context) -> Result<String> {
     use futures::future::FutureExt;
 
@@ -435,7 +436,7 @@ async fn decrypt_setup_file<T: std::io::Read + std::io::Seek>(
     Ok(plain_text)
 }
 
-pub fn normalize_setup_code(s: &str) -> String {
+fn normalize_setup_code(s: &str) -> String {
     let mut out = String::new();
     for c in s.chars() {
         if ('0'..='9').contains(&c) {

src/job.rs

@@ -1,4 +1,4 @@
-//! # Job module
+//! # Job module.
 //!
 //! This module implements a job queue maintained in the SQLite database
 //! and job types.

src/key.rs

@@ -1,4 +1,4 @@
-//! Cryptographic key module
+//! Cryptographic key module.
 
 use std::collections::BTreeMap;
 use std::fmt;

src/lib.rs

@@ -1,3 +1,5 @@
+//! # Delta Chat Core Library.
+
 #![forbid(unsafe_code)]
 #![deny(
     clippy::correctness,
@@ -59,7 +61,7 @@ mod imap;
 pub mod imex;
 mod scheduler;
 #[macro_use]
-pub mod job;
+mod job;
 mod format_flowed;
 pub mod key;
 mod keyring;

src/location.rs

@@ -1,4 +1,4 @@
-//! Location handling
+//! Location handling.
 use std::convert::TryFrom;
 
 use anyhow::{ensure, Error};

src/log.rs

@@ -1,4 +1,5 @@
-//! # Logging
+//! # Logging.
+
 use crate::context::Context;
 
 #[macro_export]

src/login_param.rs

@@ -1,4 +1,4 @@
-//! # Login parameters
+//! # Login parameters.
 
 use std::borrow::Cow;
 use std::fmt;

src/lot.rs

@@ -1,3 +1,5 @@
+//! # Legacy generic return values for C API.
+
 use deltachat_derive::{FromSql, ToSql};
 
 use crate::key::Fingerprint;

src/message.rs

@@ -1,4 +1,4 @@
-//! # Messages and their identifiers
+//! # Messages and their identifiers.
 
 use std::collections::BTreeMap;
 use std::convert::TryInto;

src/mimefactory.rs

@@ -1,3 +1,5 @@
+//! # MIME message production.
+
 use std::convert::TryInto;
 
 use anyhow::{bail, ensure, format_err, Result};

src/mimeparser.rs

@@ -1,3 +1,5 @@
+//! # MIME message parsing module.
+
 use std::collections::{HashMap, HashSet};
 use std::future::Future;
 use std::pin::Pin;

src/oauth2.rs

@@ -1,4 +1,4 @@
-//! OAuth 2 module
+//! OAuth 2 module.
 
 use std::collections::HashMap;
 

src/peerstate.rs

@@ -1,4 +1,4 @@
-//! # [Autocrypt Peer State](https://autocrypt.org/level1.html#peer-state-management) module
+//! # [Autocrypt Peer State](https://autocrypt.org/level1.html#peer-state-management) module.
 
 use std::collections::HashSet;
 use std::fmt;

src/pgp.rs

@@ -1,4 +1,4 @@
-//! OpenPGP helper module using [rPGP facilities](https://github.com/rpgp/rpgp)
+//! OpenPGP helper module using [rPGP facilities](https://github.com/rpgp/rpgp).
 
 use std::collections::{BTreeMap, HashSet};
 use std::io;

src/plaintext.rs

@@ -1,4 +1,5 @@
-///! Handle plain text together with some attributes.
+//! Handle plain text together with some attributes.
+
 use crate::simplify::split_lines;
 use once_cell::sync::Lazy;
 

src/provider.rs

@@ -1,4 +1,4 @@
-//! [Provider database](https://providers.delta.chat/) module
+//! [Provider database](https://providers.delta.chat/) module.
 
 mod data;
 

src/qr.rs

@@ -1,4 +1,4 @@
-//! # QR code module
+//! # QR code module.
 
 use anyhow::{bail, ensure, format_err, Error};
 use once_cell::sync::Lazy;

src/quota.rs

@@ -1,3 +1,5 @@
+//! # Support for IMAP QUOTA extension.
+
 use anyhow::{anyhow, Result};
 use async_imap::types::{Quota, QuotaResource};
 use indexmap::IndexMap;

src/securejoin.rs

@@ -1,4 +1,4 @@
-//! Verified contact protocol implementation as [specified by countermitm project](https://countermitm.readthedocs.io/en/stable/new.html#setup-contact-protocol)
+//! Verified contact protocol implementation as [specified by countermitm project](https://countermitm.readthedocs.io/en/stable/new.html#setup-contact-protocol).
 
 use std::convert::TryFrom;
 use std::time::{Duration, Instant};

src/simplify.rs

@@ -1,3 +1,5 @@
+//! # Simplify incoming plaintext.
+
 use itertools::Itertools;
 
 // protect lines starting with `--` against being treated as a footer.
@@ -241,9 +243,7 @@ fn render_message(lines: &[&str], is_cut_at_end: bool) -> String {
     ret.replace("\u{200B}", "")
 }
 
-/**
- * Tools
- */
+/// Returns true if the line contains only whitespace.
 fn is_empty_line(buf: &str) -> bool {
     buf.chars().all(char::is_whitespace)
     // for some time, this checked for `char <= ' '`,

src/smtp.rs

@@ -1,4 +1,4 @@
-//! # SMTP transport module
+//! # SMTP transport module.
 
 pub mod send;
 

src/sql.rs

@@ -1,4 +1,4 @@
-//! # SQLite wrapper
+//! # SQLite wrapper.
 
 use async_std::path::Path;
 use async_std::sync::RwLock;

src/sql/migrations.rs

@@ -1,3 +1,5 @@
+//! Migrations module.
+
 use anyhow::Result;
 
 use crate::config::Config;

src/stock_str.rs

@@ -1,4 +1,4 @@
-//! Module to work with translatable stock strings
+//! Module to work with translatable stock strings.
 
 use std::future::Future;
 use std::pin::Pin;

src/token.rs

@@ -1,4 +1,4 @@
-//! # Token module
+//! # Token module.
 //!
 //! Functions to read/write token from/to the database. A token is any string associated with a key.
 //!