Improve documentation

src/chat.rs

@@ -497,7 +497,7 @@ impl Chat {
 /// chat messages, use dc_get_chat_msgs().
 ///
 /// If the user is asked before creation, he should be
-/// asked whether he wants to chat with the _contact_ belonging to the message;
+/// asked whether he wants to chat with the *contact* belonging to the message;
 /// the group names may be really weird when taken from the subject of implicit
 /// groups and this may look confusing.
 ///

src/chatlist.rs

@@ -60,7 +60,7 @@ impl Chatlist {
     ///   or "Not now".
     ///   The UI can also offer a "Close" button that calls dc_marknoticed_contact() then.
     /// - DC_CHAT_ID_ARCHIVED_LINK (6) - this special chat is present if the user has
-    ///   archived _any_ chat using dc_archive_chat(). The UI should show a link as
+    ///   archived *any* chat using dc_archive_chat(). The UI should show a link as
     ///   "Show archived chats", if the user clicks this item, the UI should show a
     ///   list of all archived chats that can be created by this function hen using
     ///   the DC_GCL_ARCHIVED_ONLY flag.
@@ -71,7 +71,7 @@ impl Chatlist {
     /// The `listflags` is a combination of flags:
     /// - if the flag DC_GCL_ARCHIVED_ONLY is set, only archived chats are returned.
     ///   if DC_GCL_ARCHIVED_ONLY is not set, only unarchived chats are returned and
-    ///   the pseudo-chat DC_CHAT_ID_ARCHIVED_LINK is added if there are _any_ archived
+    ///   the pseudo-chat DC_CHAT_ID_ARCHIVED_LINK is added if there are *any* archived
     ///   chats
     /// - if the flag DC_GCL_NO_SPECIALS is set, deaddrop and archive link are not added
     ///   to the list (may be used eg. for selecting chats on forwarding, the flag is

src/contact.rs

@@ -23,15 +23,17 @@ use crate::stock::StockMessage;
 const DC_ORIGIN_MIN_CONTACT_LIST: i32 = 0x100;
 
 /// An object representing a single contact in memory.
+///
 /// The contact object is not updated.
 /// If you want an update, you have to recreate the object.
 ///
 /// The library makes sure
 /// only to use names _authorized_ by the contact in `To:` or `Cc:`.
-/// _Given-names _as "Daddy" or "Honey" are not used there.
+/// *Given-names* as "Daddy" or "Honey" are not used there.
 /// For this purpose, internally, two names are tracked -
-/// authorized-name and given-name.
+/// authorized name and given name.
 /// By default, these names are equal, but functions working with contact names
+/// only affect the given name.
 #[derive(Debug)]
 pub struct Contact {
     /// The contact ID.
@@ -203,7 +205,7 @@ impl Contact {
     /// Add a single contact as a result of an _explicit_ user action.
     ///
     /// We assume, the contact name, if any, is entered by the user and is used "as is" therefore,
-    /// normalize() is _not_ called for the name. If the contact is blocked, it is unblocked.
+    /// normalize() is *not* called for the name. If the contact is blocked, it is unblocked.
     ///
     /// To add a number of contacts, see `dc_add_address_book()` which is much faster for adding
     /// a bunch of addresses.
@@ -233,7 +235,7 @@ impl Contact {
     }
 
     /// Mark all messages sent by the given contact
-    /// as _noticed_.  See also dc_marknoticed_chat() and dc_markseen_msgs()
+    /// as *noticed*.  See also dc_marknoticed_chat() and dc_markseen_msgs()
     ///
     /// Calling this function usually results in the event `#DC_EVENT_MSGS_CHANGED`.
     pub fn mark_noticed(context: &Context, id: u32) {
@@ -423,7 +425,7 @@ impl Contact {
     /// the event `DC_EVENT_CONTACTS_CHANGED` is sent.
     ///
     /// To add a single contact entered by the user, you should prefer `Contact::create`,
-    /// however, for adding a bunch of addresses, this function is _much_ faster.
+    /// however, for adding a bunch of addresses, this function is much faster.
     ///
     /// The `addr_book` is a multiline string in the format `Name one\nAddress one\nName two\nAddress two`.
     ///

src/context.rs

@@ -1,3 +1,5 @@
+//! Contacts module
+
 use std::collections::HashMap;
 use std::ffi::OsString;
 use std::path::{Path, PathBuf};

src/error.rs

@@ -1,3 +1,5 @@
+//! # Error handling
+
 use failure::Fail;
 use lettre_email::mime;
 

src/events.rs

@@ -1,3 +1,5 @@
+//! # Events specification
+
 use std::path::PathBuf;
 
 use strum::EnumProperty;
@@ -90,7 +92,7 @@ pub enum Event {
     /// However, for ongoing processes (eg. configure())
     /// or for functions that are expected to fail (eg. dc_continue_key_transfer())
     /// it might be better to delay showing these events until the function has really
-    /// failed (returned false). It should be sufficient to report only the _last_ error
+    /// failed (returned false). It should be sufficient to report only the *last* error
     /// in a messasge box then.
     ///
     /// @return

src/imex.rs

@@ -53,7 +53,7 @@ pub enum ImexMode {
 /// For this purpose, the function creates a job that is executed in the IMAP-thread then;
 /// this requires to call dc_perform_inbox_jobs() regularly.
 ///
-/// What to do is defined by the _what_ parameter.
+/// What to do is defined by the *what* parameter.
 ///
 /// While dc_imex() returns immediately, the started job may take a while,
 /// you can stop it using dc_stop_ongoing_process(). During execution of the job,

src/job.rs

@@ -1,3 +1,8 @@
+//! # Job module
+//!
+//! This module implements a job queue maintained in the SQLite database
+//! and job types.
+
 use std::time::Duration;
 
 use deltachat_derive::{FromSql, ToSql};
@@ -117,6 +122,7 @@ pub struct Job {
 }
 
 impl Job {
+    /// Deletes the job from the database.
     fn delete(&self, context: &Context) -> bool {
         context
             .sql
@@ -124,6 +130,9 @@ impl Job {
             .is_ok()
     }
 
+    /// Updates the job already stored in the database.
+    ///
+    /// To add a new job, use [job_add].
     fn update(&self, context: &Context) -> bool {
         sql::execute(
             context,
@@ -893,6 +902,8 @@ fn add_smtp_job(
     Ok(())
 }
 
+/// Adds a job to the database, scheduling it `delay_seconds`
+/// after the current time.
 pub fn job_add(
     context: &Context,
     action: Action,

src/login_param.rs

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

src/lot.rs

@@ -5,7 +5,7 @@ use deltachat_derive::{FromSql, ToSql};
 /// Lot objects are created
 /// eg. by chatlist.get_summary() or dc_msg_get_summary().
 ///
-/// _Lot_ is used in the meaning _heap_ here.
+/// *Lot* is used in the meaning *heap* here.
 #[derive(Default, Debug, Clone)]
 pub struct Lot {
     pub(crate) text1_meaning: Meaning,

src/message.rs

@@ -1,3 +1,5 @@
+//! # Messages and their identifiers
+
 use std::path::{Path, PathBuf};
 
 use deltachat_derive::{FromSql, ToSql};

src/param.rs

@@ -50,8 +50,8 @@ pub enum Param {
     Error = b'L',
     /// For Messages: space-separated list of messaged IDs of forwarded copies.
     ///
-    /// This is used when a [Message] is in the
-    /// [MessageState::OutPending] state but is already forwarded.
+    /// This is used when a [crate::message::Message] is in the
+    /// [crate::message::MessageState::OutPending] state but is already forwarded.
     /// In this case the forwarded messages are written to the
     /// database and their message IDs are added to this parameter of
     /// the original message, which is also saved in the database.