Merge pull request #2937 from sylvestre/doc-ci

Fix the doc warnings and add a check to make sure we don't regress

.github/workflows/CICD.yml

@@ -250,6 +250,56 @@ jobs:
         S=$(cspell ${CSPELL_CFG_OPTION} --no-summary "**/*") && printf "%s\n" "$S" || { printf "%s\n" "$S" ; printf "%s" "$S" | sed -E -n "s/${PWD//\//\\/}\/(.*):(.*):(.*) - (.*)/::${fault_type} file=\1,line=\2,col=\3::${fault_type^^}: \4 (file:'\1', line:\2)/p" ; fault=true ; true ; }
         if [ -n "${{ steps.vars.outputs.FAIL_ON_FAULT }}" ] && [ -n "$fault" ]; then exit 1 ; fi
 
+  doc_warnings:
+    name: Documentation/warnings
+    runs-on: ${{ matrix.job.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        job:
+          - { os: ubuntu-latest  , features: feat_os_unix }
+# for now, don't build it on mac & windows because the doc is only published from linux
+# + it needs a bunch of duplication for build
+# and I don't want to add a doc step in the regular build to avoid long builds
+#          - { os: macos-latest   , features: feat_os_macos }
+#          - { os: windows-latest , features: feat_os_windows }
+    steps:
+    - uses: actions/checkout@v2
+    - name: Initialize workflow variables
+      id: vars
+      shell: bash
+      run: |
+        ## VARs setup
+        outputs() { step_id="vars"; for var in "$@" ; do echo steps.${step_id}.outputs.${var}="${!var}"; echo ::set-output name=${var}::${!var}; done; }
+        # failure mode
+        unset FAIL_ON_FAULT ; case '${{ env.STYLE_FAIL_ON_FAULT }}' in
+          ''|0|f|false|n|no|off) FAULT_TYPE=warning ;;
+          *) FAIL_ON_FAULT=true ; FAULT_TYPE=error ;;
+        esac;
+        outputs FAIL_ON_FAULT FAULT_TYPE
+        # target-specific options
+        # * CARGO_FEATURES_OPTION
+        CARGO_FEATURES_OPTION='--all-features' ;
+        if [ -n "${{ matrix.job.features }}" ]; then CARGO_FEATURES_OPTION='--features "${{ matrix.job.features }}"' ; fi
+        outputs CARGO_FEATURES_OPTION
+        # * determine sub-crate utility list
+        UTILITY_LIST="$(./util/show-utils.sh ${CARGO_FEATURES_OPTION})"
+        echo UTILITY_LIST=${UTILITY_LIST}
+        CARGO_UTILITY_LIST_OPTIONS="$(for u in ${UTILITY_LIST}; do echo "-puu_${u}"; done;)"
+        outputs CARGO_UTILITY_LIST_OPTIONS
+    - name: Install `rust` toolchain
+      uses: actions-rs/toolchain@v1
+      with:
+        toolchain: stable
+        default: true
+        profile: minimal # minimal component installation (ie, no documentation)
+        components: clippy
+    - name: "`cargo doc` with warnings"
+      shell: bash
+      run: |
+        RUSTDOCFLAGS="-Dwarnings" cargo doc  ${{ steps.vars.outputs.CARGO_FEATURES_OPTION }} --no-deps --workspace --document-private-items
+
+
   min_version:
     name: MinRustV # Minimum supported rust version (aka, MinSRV or MSRV)
     runs-on: ${{ matrix.job.os }}

src/uu/csplit/src/csplit.rs

@@ -1,4 +1,6 @@
 #![crate_name = "uu_csplit"]
+// spell-checker:ignore rustdoc
+#![allow(rustdoc::private_intra_doc_links)]
 
 #[macro_use]
 extern crate uucore;
@@ -83,12 +85,12 @@ impl CsplitOptions {
 /// # Errors
 ///
 /// - [`io::Error`] if there is some problem reading/writing from/to a file.
-/// - [`::CsplitError::LineOutOfRange`] if the line number pattern is larger than the number of input
+/// - [`CsplitError::LineOutOfRange`] if the line number pattern is larger than the number of input
 ///   lines.
-/// - [`::CsplitError::LineOutOfRangeOnRepetition`], like previous but after applying the pattern
+/// - [`CsplitError::LineOutOfRangeOnRepetition`], like previous but after applying the pattern
 ///   more than once.
-/// - [`::CsplitError::MatchNotFound`] if no line matched a regular expression.
-/// - [`::CsplitError::MatchNotFoundOnRepetition`], like previous but after applying the pattern
+/// - [`CsplitError::MatchNotFound`] if no line matched a regular expression.
+/// - [`CsplitError::MatchNotFoundOnRepetition`], like previous but after applying the pattern
 ///   more than once.
 pub fn csplit<T>(
     options: &CsplitOptions,
@@ -243,7 +245,7 @@ impl<'a> SplitWriter<'a> {
     }
 
     /// Writes the line to the current split, appending a newline character.
-    /// If [`dev_null`] is true, then the line is discarded.
+    /// If [`self.dev_null`] is true, then the line is discarded.
     ///
     /// # Errors
     ///
@@ -264,8 +266,8 @@ impl<'a> SplitWriter<'a> {
     }
 
     /// Perform some operations after completing a split, i.e., either remove it
-    /// if the [`::ELIDE_EMPTY_FILES_OPT`] option is enabled, or print how much bytes were written
-    /// to it if [`::QUIET_OPT`] is disabled.
+    /// if the [`options::ELIDE_EMPTY_FILES`] option is enabled, or print how much bytes were written
+    /// to it if [`options::QUIET`] is disabled.
     ///
     /// # Errors
     ///
@@ -305,7 +307,7 @@ impl<'a> SplitWriter<'a> {
     ///
     /// In addition to errors reading/writing from/to a file, if the line number
     /// `n` is greater than the total available lines, then a
-    /// [`::CsplitError::LineOutOfRange`] error is returned.
+    /// [`CsplitError::LineOutOfRange`] error is returned.
     fn do_to_line<I>(
         &mut self,
         pattern_as_str: &str,
@@ -354,9 +356,9 @@ impl<'a> SplitWriter<'a> {
     /// # Errors
     ///
     /// In addition to errors reading/writing from/to a file, the following errors may be returned:
-    /// - if no line matched, an [`::CsplitError::MatchNotFound`].
+    /// - if no line matched, an [`CsplitError::MatchNotFound`].
     /// - if there are not enough lines to accommodate the offset, an
-    /// [`::CsplitError::LineOutOfRange`].
+    /// [`CsplitError::LineOutOfRange`].
     fn do_to_match<I>(
         &mut self,
         pattern_as_str: &str,
@@ -512,7 +514,7 @@ where
         self.size = size;
     }
 
-    /// Add a line to the buffer. If the buffer has [`size`] elements, then its head is removed and
+    /// Add a line to the buffer. If the buffer has [`self.size`] elements, then its head is removed and
     /// the new line is pushed to the buffer. The removed head is then available in the returned
     /// option.
     fn add_line_to_buffer(&mut self, ln: usize, line: String) -> Option<String> {

src/uu/csplit/src/patterns.rs

@@ -88,7 +88,7 @@ impl Iterator for ExecutePatternIter {
 ///
 /// # Errors
 ///
-/// If a pattern is incorrect, a [`::CsplitError::InvalidPattern`] error is returned, which may be
+/// If a pattern is incorrect, a [`CsplitError::InvalidPattern`] error is returned, which may be
 /// due to, e.g.,:
 /// - an invalid regular expression;
 /// - an invalid number for, e.g., the offset.

src/uu/date/src/date.rs

@@ -377,9 +377,9 @@ fn set_system_datetime(_date: DateTime<Utc>) -> UResult<()> {
 #[cfg(all(unix, not(target_os = "macos"), not(target_os = "redox")))]
 /// System call to set date (unix).
 /// See here for more:
-/// https://doc.rust-lang.org/libc/i686-unknown-linux-gnu/libc/fn.clock_settime.html
-/// https://linux.die.net/man/3/clock_settime
-/// https://www.gnu.org/software/libc/manual/html_node/Time-Types.html
+/// `<https://doc.rust-lang.org/libc/i686-unknown-linux-gnu/libc/fn.clock_settime.html>`
+/// `<https://linux.die.net/man/3/clock_settime>`
+/// `<https://www.gnu.org/software/libc/manual/html_node/Time-Types.html>`
 fn set_system_datetime(date: DateTime<Utc>) -> UResult<()> {
     let timespec = timespec {
         tv_sec: date.timestamp() as _,

src/uu/dd/src/parseargs.rs

@@ -86,7 +86,7 @@ impl UError for ParseError {
     }
 }
 
-/// Some flags specified as part of a conv=CONV[,CONV]... block
+/// Some flags specified as part of a conv=CONV\[,CONV\]... block
 /// relate to the input file, others to the output file.
 #[derive(Debug, PartialEq)]
 enum ConvFlag {

src/uu/head/src/lines.rs

@@ -9,7 +9,7 @@ const ZERO: u8 = 0;
 /// Returns an iterator over the lines of the given reader.
 ///
 /// The iterator returned from this function will yield instances of
-/// [`io::Result`]<[`Vec`]<[`u8`]>>, representing the bytes of the line
+/// [`std::io::Result`]<[`Vec`]<[`u8`]>>, representing the bytes of the line
 /// *including* the null character (with the possible exception of the
 /// last line, which may not have one).
 ///

src/uu/head/src/parse.rs

@@ -12,7 +12,7 @@ pub enum ParseError {
     Overflow,
 }
 /// Parses obsolete syntax
-/// head -NUM[kmzv] // spell-checker:disable-line
+/// head -NUM\[kmzv\] // spell-checker:disable-line
 pub fn parse_obsolete(src: &str) -> Option<Result<impl Iterator<Item = OsString>, ParseError>> {
     let mut chars = src.char_indices();
     if let Some((_, '-')) = chars.next() {

src/uu/head/src/take.rs

@@ -65,7 +65,7 @@ where
 /// Like `std::io::Take`, but for lines instead of bytes.
 ///
 /// This struct is generally created by calling [`take_lines`] on a
-/// reader. Please see the documentation of [`take`] for more
+/// reader. Please see the documentation of [`take_lines`] for more
 /// details.
 pub struct TakeLines<T> {
     inner: T,

src/uu/install/src/install.rs

@@ -681,7 +681,7 @@ fn copy(from: &Path, to: &Path, b: &Behavior) -> UResult<()> {
 /// Return true if a file is necessary to copy. This is the case when:
 ///
 /// - _from_ or _to_ is nonexistent;
-/// - either file has a sticky bit or set[ug]id bit, or the user specified one;
+/// - either file has a sticky bit or set\[ug\]id bit, or the user specified one;
 /// - either file isn't a regular file;
 /// - the sizes of _from_ and _to_ differ;
 /// - _to_'s owner differs from intended; or

src/uu/seq/src/number.rs

@@ -4,7 +4,7 @@
 //! The [`Number`] enumeration represents the possible values for the
 //! start, increment, and end values for `seq`. These may be integers,
 //! floating point numbers, negative zero, etc. A [`Number`] can be
-//! parsed from a string by calling [`parse`].
+//! parsed from a string by calling [`str::parse`].
 use num_traits::Zero;
 
 use crate::extendedbigdecimal::ExtendedBigDecimal;
@@ -77,7 +77,7 @@ impl Number {
 ///
 /// This struct can be used to represent a number along with information
 /// on how many significant digits to use when displaying the number.
-/// The [`num_integral_digits`] field also includes the width needed to
+/// The [`PreciseNumber::num_integral_digits`] field also includes the width needed to
 /// display the "-" character for a negative number.
 ///
 /// You can get an instance of this struct by calling [`str::parse`].

src/uu/shuf/src/rand_read_adapter.rs

@@ -29,7 +29,7 @@ use rand_core::{impls, Error, RngCore};
 /// have enough data, will only be reported through [`try_fill_bytes`].
 /// The other [`RngCore`] methods will panic in case of an error.
 ///
-/// [`OsRng`]: crate::rngs::OsRng
+/// [`OsRng`]: rand::rngs::OsRng
 /// [`try_fill_bytes`]: RngCore::try_fill_bytes
 #[derive(Debug)]
 pub struct ReadRng<R> {

src/uu/tail/src/chunks.rs

@@ -13,7 +13,7 @@ pub const BLOCK_SIZE: u64 = 1 << 16;
 ///
 /// Each chunk is a [`Vec`]<[`u8`]> of size [`BLOCK_SIZE`] (except
 /// possibly the last chunk, which might be smaller). Each call to
-/// [`next`] will seek backwards through the given file.
+/// [`ReverseChunks::next`] will seek backwards through the given file.
 pub struct ReverseChunks<'a> {
     /// The file to iterate over, by blocks, from the end to the beginning.
     file: &'a File,

src/uu/tail/src/parse.rs

@@ -11,7 +11,7 @@ pub enum ParseError {
     Overflow,
 }
 /// Parses obsolete syntax
-/// tail -NUM[kmzv] // spell-checker:disable-line
+/// tail -NUM\[kmzv\] // spell-checker:disable-line
 pub fn parse_obsolete(src: &str) -> Option<Result<impl Iterator<Item = OsString>, ParseError>> {
     let mut chars = src.char_indices();
     if let Some((_, '-')) = chars.next() {

src/uu/wc/src/countable.rs

@@ -1,7 +1,7 @@
 //! Traits and implementations for iterating over lines in a file-like object.
 //!
 //! This module provides a [`WordCountable`] trait and implementations
-//! for some common file-like objects. Use the [`WordCountable::lines`]
+//! for some common file-like objects. Use the [`WordCountable::buffered`]
 //! method to get an iterator over lines of a file-like object.
 use std::fs::File;
 use std::io::{BufRead, BufReader, Read, StdinLock};

src/uucore/src/lib/features/pipes.rs

@@ -9,7 +9,7 @@ use nix::{fcntl::SpliceFFlags, sys::uio::IoVec};
 
 pub use nix::{Error, Result};
 
-/// A wrapper around [`nix::unistd::Pipe`] that ensures the pipe is cleaned up.
+/// A wrapper around [`nix::unistd::pipe`] that ensures the pipe is cleaned up.
 ///
 /// Returns two `File` objects: everything written to the second can be read
 /// from the first.

src/uucore/src/lib/features/ringbuffer.rs

@@ -33,6 +33,9 @@ use std::collections::VecDeque;
 /// let expected = VecDeque::from_iter([1, 2].iter());
 /// assert_eq!(expected, actual);
 /// ```
+///
+/// [`push_back`]: struct.RingBuffer.html#method.push_back
+/// [`from_iter`]: struct.RingBuffer.html#method.from_iter
 pub struct RingBuffer<T> {
     pub data: VecDeque<T>,
     size: usize,

src/uucore/src/lib/macros.rs

@@ -221,7 +221,7 @@ macro_rules! show_usage_error(
     })
 );
 
-/// Display an error and [`exit!`]
+/// Display an error and [`std::process::exit`]
 ///
 /// Displays the provided error message using [`show_error!`], then invokes
 /// [`std::process::exit`] with the provided exit code.

src/uucore/src/lib/mods/backup_control.rs

@@ -129,7 +129,7 @@ pub enum BackupMode {
 /// Backup error types.
 ///
 /// Errors are currently raised by [`determine_backup_mode`] only. All errors
-/// are implemented as [`UCustomError`] for uniform handling across utilities.
+/// are implemented as [`UError`] for uniform handling across utilities.
 #[derive(Debug, Eq, PartialEq)]
 pub enum BackupError {
     /// An invalid argument (e.g. 'foo') was given as backup type. First

src/uucore/src/lib/mods/panic.rs

@@ -26,11 +26,11 @@ fn is_broken_pipe(info: &PanicInfo) -> bool {
 ///
 /// For background discussions on `SIGPIPE` handling, see
 ///
-/// * https://github.com/uutils/coreutils/issues/374
-/// * https://github.com/uutils/coreutils/pull/1106
-/// * https://github.com/rust-lang/rust/issues/62569
-/// * https://github.com/BurntSushi/ripgrep/issues/200
-/// * https://github.com/crev-dev/cargo-crev/issues/287
+/// * `<https://github.com/uutils/coreutils/issues/374>`
+/// * `<https://github.com/uutils/coreutils/pull/1106>`
+/// * `<https://github.com/rust-lang/rust/issues/62569>`
+/// * `<https://github.com/BurntSushi/ripgrep/issues/200>`
+/// * `<https://github.com/crev-dev/cargo-crev/issues/287>`
 ///
 pub fn mute_sigpipe_panic() {
     let hook = panic::take_hook();