Add rustdoc to CI and fix some doc comments

This fixes a bunch of doc comments and also adds the run to CI so that
failures get caught early.

.github/workflows/ci.yml

@@ -40,6 +40,28 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           args: --workspace --tests --examples
 
+  docs:
+    name: Rust doc comments
+    runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: -Dwarnings
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v2
+      - name: Install rust stable toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          profile: minimal
+          components: rust-docs
+          override: true
+      - name: Cache rust cargo artifacts
+        uses: swatinem/rust-cache@v1
+      - name: Rustdoc
+        uses: actions-rs/cargo@v1
+        with:
+          command: doc
+          args: --workspace --document-private-items --no-deps
 
   build_and_test:
     name: Build and test

src/chat.rs

@@ -133,8 +133,10 @@ impl ChatId {
 
     /// Chat ID signifying there are **any** number of archived chats.
     ///
-    /// This chat ID can be returned in a [Chatlist] and signals to
+    /// This chat ID can be returned in a [`Chatlist`] and signals to
     /// the UI to include a link to the archived chats.
+    ///
+    /// [`Chatlist`]: crate::chatlist::Chatlist
     pub fn is_archived_link(self) -> bool {
         self.0 == DC_CHAT_ID_ARCHIVED_LINK
     }
@@ -142,8 +144,11 @@ impl ChatId {
     /// Virtual chat ID signalling there are **only** archived chats.
     ///
     /// This can be included in the chatlist if the
-    /// [DC_GCL_ADD_ALLDONE_HINT] flag is used to build the
+    /// [`DC_GCL_ADD_ALLDONE_HINT`] flag is used to build the
-    /// [Chatlist].
+    /// [`Chatlist`].
+    ///
+    /// [`DC_GCL_ADD_ALLDONE_HINT`]: crate::constants::DC_GCL_ADD_ALLDONE_HINT
+    /// [`Chatlist`]: crate::chatlist::Chatlist
     pub fn is_alldone_hint(self) -> bool {
         self.0 == DC_CHAT_ID_ALLDONE_HINT
     }
@@ -1172,7 +1177,7 @@ pub struct ChatInfo {
 
     /// The "params" of the chat.
     ///
-    /// This is the string-serialised version of [Params] currently.
+    /// This is the string-serialised version of `Params` currently.
     pub param: String,
 
     /// Last time this client sent autocrypt gossip headers to this chat.
@@ -1257,8 +1262,9 @@ pub async fn create_by_msg_id(context: &Context, msg_id: MsgId) -> Result<ChatId
     Ok(chat.id)
 }
 
-/// Create a normal chat with a single user.  To create group chats,
+/// Create a normal chat with a single user.
-/// see [Chat::create_group_chat].
+///
+/// To create group chats, see [`create_group_chat`].
 ///
 /// If a chat already exists, this ID is returned, otherwise a new chat is created;
 /// this new chat may already contain messages, eg. from the deaddrop, to get the

src/events.rs

@@ -80,6 +80,8 @@ impl async_std::stream::Stream for EventEmitter {
 /// documented in `deltachat.h`.
 ///
 /// This struct [`Deref`]s to the [`EventType`].
+///
+/// [`Context`]: crate::context::Context
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Event {
     /// The ID of the [`Context`] which emitted this event.

src/securejoin.rs

@@ -369,7 +369,7 @@ async fn securejoin(context: &Context, qr: &str) -> Result<ChatId, JoinError> {
     }
 }
 
-/// Error for [send_handshake_msg].
+/// Error when failing to send a protocol handshake message.
 ///
 /// Wrapping the [anyhow::Error] means we can "impl From" more easily on errors from this
 /// function.
@@ -489,9 +489,8 @@ pub(crate) enum HandshakeMessage {
 
 /// Handle incoming secure-join handshake.
 ///
-/// This function will update the securejoin state in [Context::bob]
+/// This function will update the securejoin state in [`InnerContext::bob`] and also
-/// and also terminate the ongoing process using
+/// terminate the ongoing process using [Context::stop_ongoing] as required by the protocol.
-/// [Context::stop_ongoing] as required by the protocol.
 ///
 /// A message which results in [Err] will be hidden from the user but
 /// not deleted, it may be a valid message for something else we are
@@ -501,6 +500,8 @@ pub(crate) enum HandshakeMessage {
 /// When handle_securejoin_handshake() is called,
 /// the message is not yet filed in the database;
 /// this is done by receive_imf() later on as needed.
+///
+/// [`InnerContext::bob`]: crate::context::InnerContext::bob
 #[allow(clippy::indexing_slicing)]
 pub(crate) async fn handle_securejoin_handshake(
     context: &Context,