From feb8b12ea1af91947a2dd05e0bb94373a5292e14 Mon Sep 17 00:00:00 2001 From: Marco Ieni <11428655+MarcoIeni@users.noreply.github.com> Date: Fri, 16 Apr 2021 00:18:16 +0200 Subject: 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 --- .github/workflows/ci.yml | 20 ++++++++++ src/hunk_header.rs | 40 ++++++++++---------- src/options/get.rs | 34 ++++++++--------- src/options/set.rs | 98 ++++++++++++++++++++++++------------------------ 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( option_name: &str, builtin_features: &HashMap, 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, -- cgit v1.2.3