CI: check docs (#559)

* CI: check docs

* Don't use triple-slash doc comments

A full pass would need to be done to make the comments suitable for
generating documentation.

Co-authored-by: Dan Davison <dandavison7@gmail.com>

4 files changed, 106 insertions, 86 deletions

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c78ae786..7f3320f7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -109,6 +109,26 @@ jobs:
           command: clippy
           args: -- -D warnings
 
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+      - name: Install Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          profile: minimal
+          override: true
+      - name: Check documentation
+        env:
+          RUSTDOCFLAGS: -D warnings
+        uses: actions-rs/cargo@v1
+        with:
+          command: doc
+          args: --no-deps --document-private-items
+
   coverage:
     name: Code coverage
     runs-on: ubuntu-latest
diff --git a/src/hunk_header.rs b/src/hunk_header.rs
index 810ebfe8..da2df606 100644
--- a/src/hunk_header.rs
+++ b/src/hunk_header.rs
@@ -1,23 +1,23 @@
-//! A module for constructing and writing the hunk header.
-//!
-//! The structure of the hunk header output by delta is
-//! ```
-//! (file):(line-number): (code-fragment)
-//! ```
-//!
-//! The code fragment and line number derive from a line of git/diff output that looks like
-//! ```
-//! @@ -119,12 +119,7 @@ fn write_to_output_buffer(
-//! ```
-//!
-//! Whether or not file and line-number are included is controlled by the presence of the special
-//! style attributes 'file' and 'line-number' in the hunk-header-style string. For example, delta
-//! might output the above hunk header as
-//! ```
-//! ───────────────────────────────────────────────────┐
-//! src/hunk_header.rs:119: fn write_to_output_buffer( │
-//! ───────────────────────────────────────────────────┘
-//! ```
+// A module for constructing and writing the hunk header.
+//
+// The structure of the hunk header output by delta is
+// ```
+// (file):(line-number): (code-fragment)
+// ```
+//
+// The code fragment and line number derive from a line of git/diff output that looks like
+// ```
+// @@ -119,12 +119,7 @@ fn write_to_output_buffer(
+// ```
+//
+// Whether or not file and line-number are included is controlled by the presence of the special
+// style attributes 'file' and 'line-number' in the hunk-header-style string. For example, delta
+// might output the above hunk header as
+// ```
+// ───────────────────────────────────────────────────┐
+// src/hunk_header.rs:119: fn write_to_output_buffer( │
+// ───────────────────────────────────────────────────┘
+// ```
 
 use std::fmt::Write as FmtWrite;
 
diff --git a/src/options/get.rs b/src/options/get.rs
index 1699e273..e946c846 100644
--- a/src/options/get.rs
+++ b/src/options/get.rs
@@ -8,23 +8,23 @@ use crate::git_config::{self, GitConfigGet};
 use crate::options::option_value::{OptionValue, ProvenancedOptionValue};
 use ProvenancedOptionValue::*;
 
-/// Look up a value of type `T` associated with `option name`. The search rules are:
-///
-/// 1. If there is a value associated with `option_name` in the main [delta] git config
-///    section, then stop searching and return that value.
-///
-/// 2. For each feature in the ordered list of enabled features:
-///
-///    2.1 Look-up the value, treating `feature` as a custom feature.
-///        I.e., if there is a value associated with `option_name` in a git config section
-///        named [delta "`feature`"] then stop searching and return that value.
-///
-///    2.2 Look-up the value, treating `feature` as a builtin feature.
-///        I.e., if there is a value (not a default value) associated with `option_name` in a
-///        builtin feature named `feature`, then stop searching and return that value.
-///        Otherwise, record the default value and continue searching.
-///
-/// 3. Return the last default value that was encountered.
+// Look up a value of type `T` associated with `option name`. The search rules are:
+//
+// 1. If there is a value associated with `option_name` in the main [delta] git config
+//    section, then stop searching and return that value.
+//
+// 2. For each feature in the ordered list of enabled features:
+//
+//    2.1 Look-up the value, treating `feature` as a custom feature.
+//        I.e., if there is a value associated with `option_name` in a git config section
+//        named [delta "`feature`"] then stop searching and return that value.
+//
+//    2.2 Look-up the value, treating `feature` as a builtin feature.
+//        I.e., if there is a value (not a default value) associated with `option_name` in a
+//        builtin feature named `feature`, then stop searching and return that value.
+//        Otherwise, record the default value and continue searching.
+//
+// 3. Return the last default value that was encountered.
 pub fn get_option_value<T>(
     option_name: &str,
     builtin_features: &HashMap<String, features::BuiltinFeature>,
diff --git a/src/options/set.rs b/src/options/set.rs
index e5c1edf0..c04bcb89 100644
--- a/src/options/set.rs
+++ b/src/options/set.rs
@@ -239,55 +239,55 @@ fn set__light__dark__syntax_theme__options(
     );
 }
 
-/// Features are processed differently from all other options. The role of this function is to
-/// collect all configuration related to features and summarize it as a single list
-/// (space-separated string) of enabled features. The list is arranged in order of increasing
-/// priority in the sense that, when searching for a option value, one starts at the right-hand end
-/// and moves leftward, examining each feature in turn until a feature that associates a value with
-/// the option name is encountered. This search is documented in
-/// `get_option_value::get_option_value`.
-///
-/// The feature list comprises features deriving from the following sources, listed in order of
-/// decreasing priority:
-///
-/// 1. Suppose the command-line has `--features "a b"`. Then
-///    - `b`, followed by b's "ordered descendents"
-///    - `a`, followed by a's "ordered descendents"
-///
-/// 2. Suppose the command line enables two builtin features via `--navigate --diff-so-fancy`. Then
-///    - `diff-so-fancy`
-///    - `navigate`
-///
-/// 3. Suppose the main [delta] section has `features = d e`. Then
-///    - `e`, followed by e's "ordered descendents"
-///    - `d`, followed by d's "ordered descendents"
-///
-/// 4. Suppose the main [delta] section has `diff-highlight = true` followed by `raw = true`.
-///    Then
-///    - `diff-highlight`
-///    - `raw`
-///
-/// The "ordered descendents" of a feature `f` is a list of features obtained via a pre-order
-/// traversal of the feature tree rooted at `f`. This tree arises because it is allowed for a
-/// feature to contain a (key, value) pair that itself enables features.
-///
-/// If a feature has already been included at higher priority, and is encountered again, it is
-/// ignored.
-///
-/// Thus, for example:
-///
-/// delta --features "my-navigate-settings" --navigate   =>   "navigate my-navigate-settings"
-///
-/// In the following configuration, the feature names indicate their priority, with `a` having
-/// highest priority:
-///
-/// delta --g --features "d a"
-///
-/// [delta "a"]
-///     features = c b
-///
-/// [delta "d"]
-///     features = f e
+// Features are processed differently from all other options. The role of this function is to
+// collect all configuration related to features and summarize it as a single list
+// (space-separated string) of enabled features. The list is arranged in order of increasing
+// priority in the sense that, when searching for a option value, one starts at the right-hand end
+// and moves leftward, examining each feature in turn until a feature that associates a value with
+// the option name is encountered. This search is documented in
+// `get_option_value::get_option_value`.
+//
+// The feature list comprises features deriving from the following sources, listed in order of
+// decreasing priority:
+//
+// 1. Suppose the command-line has `--features "a b"`. Then
+//    - `b`, followed by b's "ordered descendents"
+//    - `a`, followed by a's "ordered descendents"
+//
+// 2. Suppose the command line enables two builtin features via `--navigate --diff-so-fancy`. Then
+//    - `diff-so-fancy`
+//    - `navigate`
+//
+// 3. Suppose the main [delta] section has `features = d e`. Then
+//    - `e`, followed by e's "ordered descendents"
+//    - `d`, followed by d's "ordered descendents"
+//
+// 4. Suppose the main [delta] section has `diff-highlight = true` followed by `raw = true`.
+//    Then
+//    - `diff-highlight`
+//    - `raw`
+//
+// The "ordered descendents" of a feature `f` is a list of features obtained via a pre-order
+// traversal of the feature tree rooted at `f`. This tree arises because it is allowed for a
+// feature to contain a (key, value) pair that itself enables features.
+//
+// If a feature has already been included at higher priority, and is encountered again, it is
+// ignored.
+//
+// Thus, for example:
+//
+// delta --features "my-navigate-settings" --navigate   =>   "navigate my-navigate-settings"
+//
+// In the following configuration, the feature names indicate their priority, with `a` having
+// highest priority:
+//
+// delta --g --features "d a"
+//
+// [delta "a"]
+//     features = c b
+//
+// [delta "d"]
+//     features = f e
 fn gather_features(
     opt: &cli::Opt,
     builtin_features: &HashMap<String, features::BuiltinFeature>,