Improve documentation and comments

src/aheader.rs

@@ -1,3 +1,7 @@
+//! # Autocrypt header module
+//!
+//! Parse and create [Autocrypt-headers](https://autocrypt.org/en/latest/level1.html#the-autocrypt-header).
+
 use std::collections::BTreeMap;
 use std::ffi::CStr;
 use std::str::FromStr;
@@ -46,7 +50,7 @@ impl str::FromStr for EncryptPreference {
     }
 }
 
-/// Parse and create [Autocrypt-headers](https://autocrypt.org/en/latest/level1.html#the-autocrypt-header).
+/// Autocrypt header
 #[derive(Debug)]
 pub struct Aheader {
     pub addr: String,
@@ -55,6 +59,7 @@ pub struct Aheader {
 }
 
 impl Aheader {
+    /// Creates new autocrypt header
     pub fn new(addr: String, public_key: Key, prefer_encrypt: EncryptPreference) -> Self {
         Aheader {
             addr,

src/blob.rs

@@ -1,3 +1,5 @@
+//! # Blob directory management
+
 use std::ffi::OsStr;
 use std::fmt;
 use std::fs;

src/chat.rs

@@ -1,3 +1,5 @@
+//! # Chat module
+
 use std::path::{Path, PathBuf};
 
 use itertools::Itertools;
@@ -37,6 +39,7 @@ pub struct Chat {
 }
 
 impl Chat {
+    /// Loads chat from the database by its ID.
     pub fn load_from_db(context: &Context, chat_id: u32) -> Result<Self, Error> {
         let res = context.sql.query_row(
             "SELECT c.id,c.type,c.name, c.grpid,c.param,c.archived, \
@@ -226,6 +229,7 @@ impl Chat {
         color
     }
 
+    /// Returns true if the chat is archived.
     pub fn is_archived(&self) -> bool {
         self.archived
     }

src/chatlist.rs

@@ -1,3 +1,5 @@
+//! # Chat list module
+
 use crate::chat::*;
 use crate::constants::*;
 use crate::contact::*;
@@ -233,6 +235,7 @@ impl Chatlist {
         self.ids.len()
     }
 
+    /// Returns true if chatlist is empty.
     pub fn is_empty(&self) -> bool {
         self.ids.is_empty()
     }
@@ -329,6 +332,7 @@ impl Chatlist {
     }
 }
 
+/// Get the number of archived chats
 pub fn dc_get_archived_cnt(context: &Context) -> u32 {
     context
         .sql

src/config.rs

@@ -1,3 +1,5 @@
+//! # Key-value configuration management
+
 use strum::{EnumProperty, IntoEnumIterator};
 use strum_macros::{AsRefStr, Display, EnumIter, EnumProperty, EnumString};
 

src/configure/auto_mozilla.rs

@@ -1,3 +1,4 @@
+//! Thunderbird's Autoconfiguration implementation
 use quick_xml;
 use quick_xml::events::{BytesEnd, BytesStart, BytesText};
 

src/configure/mod.rs

@@ -1,3 +1,5 @@
+//! Email accounts autoconfiguration process module
+
 use percent_encoding::{utf8_percent_encode, NON_ALPHANUMERIC};
 
 use crate::config::Config;
@@ -563,9 +565,7 @@ fn try_smtp_one_param(context: &Context, param: &LoginParam) -> Option<bool> {
     }
 }
 
-/*******************************************************************************
+/// Connects to the configured account
- * Connect to configured account
- ******************************************************************************/
 pub fn dc_connect_to_configured_imap(context: &Context, imap: &Imap) -> libc::c_int {
     let mut ret_connected = 0;
 

src/constants.rs

@@ -1,4 +1,4 @@
-//! Constants
+//! # Constants
 #![allow(non_camel_case_types, dead_code)]
 
 use deltachat_derive::*;

src/contact.rs

@@ -47,8 +47,8 @@ pub struct Contact {
     /// May be empty, initially set to `authname`.
     name: String,
     /// Name authorized by the contact himself. Only this name may be spread to others,
-    /// e.g. in To:-lists. May be empty. It is recommended to use `Contact::get_name`,
+    /// e.g. in To:-lists. May be empty. It is recommended to use `Contact::get_authname`,
-    /// `Contact::get_display_name` or `Contact::get_name_n_addr` to access this field.
+    /// to access this field.
     authname: String,
     /// E-Mail-Address of the contact. It is recommended to use `Contact::get_addr`` to access this field.
     addr: String,
@@ -717,6 +717,7 @@ impl Contact {
         &self.addr
     }
 
+    /// Get name authorized by the contact.
     pub fn get_authname(&self) -> &str {
         &self.authname
     }
@@ -899,6 +900,7 @@ impl Contact {
     }
 }
 
+/// Extracts first name from full name.
 fn get_first_name<'a>(full_name: &'a str) -> &'a str {
     full_name.splitn(2, ' ').next().unwrap_or_default()
 }
@@ -909,6 +911,7 @@ pub fn may_be_valid_addr(addr: &str) -> bool {
     res.is_ok()
 }
 
+/// Returns address with whitespace trimmed and `mailto:` prefix removed.
 pub fn addr_normalize(addr: &str) -> &str {
     let norm = addr.trim();
 

src/context.rs

@@ -39,7 +39,9 @@ pub type ContextCallback = dyn Fn(&Context, Event) -> uintptr_t + Send + Sync;
 
 #[derive(DebugStub)]
 pub struct Context {
+    /// Database file path
     dbfile: PathBuf,
+    /// Blob directory path
     blobdir: PathBuf,
     pub sql: Sql,
     pub inbox: Arc<RwLock<Imap>>,
@@ -93,6 +95,7 @@ pub fn get_info() -> HashMap<&'static str, String> {
 }
 
 impl Context {
+    /// Creates new context.
     pub fn new(cb: Box<ContextCallback>, os_name: String, dbfile: PathBuf) -> Result<Context> {
         let mut blob_fname = OsString::new();
         blob_fname.push(dbfile.file_name().unwrap_or_default());
@@ -153,10 +156,12 @@ impl Context {
         Ok(ctx)
     }
 
+    /// Returns database file path.
     pub fn get_dbfile(&self) -> &Path {
         self.dbfile.as_path()
     }
 
+    /// Returns blob directory path.
     pub fn get_blobdir(&self) -> &Path {
         self.blobdir.as_path()
     }

src/imex.rs

@@ -1,3 +1,5 @@
+//! # Import/export module
+
 use core::cmp::{max, min};
 use std::path::Path;
 

src/key.rs

@@ -1,3 +1,5 @@
+//! Cryptographic key module
+
 use std::collections::BTreeMap;
 use std::io::Cursor;
 use std::path::Path;
@@ -11,6 +13,7 @@ use crate::context::Context;
 use crate::dc_tools::*;
 use crate::sql::{self, Sql};
 
+/// Cryptographic key
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub enum Key {
     Public(SignedPublicKey),

src/location.rs

@@ -1,3 +1,5 @@
+//! Location handling
+
 use bitflags::bitflags;
 use quick_xml;
 use quick_xml::events::{BytesEnd, BytesStart, BytesText};
@@ -16,7 +18,7 @@ use crate::param::*;
 use crate::sql;
 use crate::stock::StockMessage;
 
-// location handling
+/// Location record
 #[derive(Debug, Clone, Default)]
 pub struct Location {
     pub location_id: u32,

src/log.rs

@@ -1,3 +1,5 @@
+//! # Logging macros
+
 #[macro_export]
 macro_rules! info {
     ($ctx:expr,  $msg:expr) => {

src/oauth2.rs

@@ -1,3 +1,5 @@
+//! OAuth 2 module
+
 use std::collections::HashMap;
 
 use percent_encoding::{utf8_percent_encode, NON_ALPHANUMERIC};
@@ -33,12 +35,14 @@ struct Oauth2 {
     get_userinfo: Option<&'static str>,
 }
 
+/// OAuth 2 Access Token Response
 #[derive(Debug, Deserialize)]
 struct Response {
     // Should always be there according to: https://www.oauth.com/oauth2-servers/access-tokens/access-token-response/
     // but previous code handled its abscense.
     access_token: Option<String>,
     token_type: String,
+    /// Duration of time the token is granted for, in seconds
     expires_in: Option<u64>,
     refresh_token: Option<String>,
     scope: Option<String>,
@@ -205,7 +209,7 @@ pub fn dc_get_oauth2_access_token(
                 .ok();
             let expires_in = response
                 .expires_in
-                // refresh a bet before
+                // refresh a bit before
                 .map(|t| time() + t as i64 - 5)
                 .unwrap_or_else(|| 0);
             context

src/peerstate.rs

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

src/pgp.rs

@@ -1,3 +1,5 @@
+//! OpenPGP helper module
+
 use std::collections::{BTreeMap, HashSet};
 use std::convert::TryInto;
 use std::io::Cursor;
@@ -106,6 +108,8 @@ fn select_pk_for_encryption(key: &SignedPublicKey) -> Option<&SignedPublicSubKey
         true)
 }
 
+/// Encrypts `plain` text using `public_keys_for_encryption`
+/// and signs it using `private_key_for_signing`.
 pub fn pk_encrypt(
     plain: &[u8],
     public_keys_for_encryption: &Keyring,

src/qr.rs

@@ -1,3 +1,5 @@
+//! # QR code module
+
 use lazy_static::lazy_static;
 use percent_encoding::percent_decode_str;
 

src/securejoin.rs

@@ -1,3 +1,5 @@
+//! Verified contact protocol implementation as [specified by countermitm project](https://countermitm.readthedocs.io/en/stable/new.html#setup-contact-protocol)
+
 use percent_encoding::{utf8_percent_encode, AsciiSet, NON_ALPHANUMERIC};
 
 use crate::aheader::EncryptPreference;

src/sql.rs

@@ -1,3 +1,5 @@
+//! # SQLite wrapper
+
 use std::collections::HashSet;
 use std::sync::{Arc, RwLock};
 use std::time::Duration;

src/stock.rs

@@ -1,3 +1,5 @@
+//! Module to work with translatable stock strings
+
 use std::borrow::Cow;
 
 use strum::EnumProperty;

src/token.rs

@@ -1,4 +1,8 @@
+//! # Token module
+//!
 //! Functions to read/write token from/to the database. A token is any string associated with a key.
+//!
+//! Tokens are used in countermitm verification protocols.
 
 use deltachat_derive::*;
 
@@ -6,7 +10,7 @@ use crate::context::Context;
 use crate::dc_tools::*;
 use crate::sql;
 
-// Token namespaces
+/// Token namespace
 #[derive(Debug, Display, Clone, Copy, PartialEq, Eq, FromPrimitive, ToPrimitive, ToSql, FromSql)]
 #[repr(i32)]
 pub enum Namespace {
@@ -21,6 +25,8 @@ impl Default for Namespace {
     }
 }
 
+/// Creates a new token and saves it into the database.
+/// Returns created token.
 pub fn save(context: &Context, namespace: Namespace, foreign_id: u32) -> String {
     // foreign_id may be 0
     let token = dc_create_id();