From 5ed0aa2864d3ceec5ea0e5e6bf68bd0458c6d7ea Mon Sep 17 00:00:00 2001 From: Nico Wagner Date: Thu, 12 Dec 2024 17:35:11 +0100 Subject: [PATCH] docs: Fix `rustdoc` warnings (#889) Signed-off-by: Nico Wagner --- .github/workflows/rust.yml | 13 ++++++++++++- crates/pica-cli/src/commands/completions.rs | 4 ++-- crates/pica-cli/src/commands/concat.rs | 4 ++-- crates/pica-cli/src/commands/convert/mod.rs | 4 ++-- crates/pica-cli/src/commands/count.rs | 4 ++-- crates/pica-cli/src/commands/explode.rs | 8 ++++---- crates/pica-cli/src/commands/filter.rs | 16 ++++++++-------- crates/pica-cli/src/commands/frequency.rs | 14 +++++++------- crates/pica-cli/src/commands/hash.rs | 4 ++-- crates/pica-cli/src/commands/partition.rs | 10 +++++----- crates/pica-cli/src/commands/print.rs | 10 +++++----- crates/pica-cli/src/commands/sample.rs | 2 +- crates/pica-cli/src/commands/select.rs | 10 +++++----- crates/pica-cli/src/commands/slice.rs | 4 ++-- crates/pica-cli/src/commands/split.rs | 2 +- 15 files changed, 60 insertions(+), 49 deletions(-) diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index a48c7ea86..a596d2ce9 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -16,9 +16,10 @@ concurrency: cancel-in-progress: true env: + CARGO_INCREMENTAL: 0 CARGO_TERM_COLOR: always + RUSTDOCFLAGS: "-Dwarnings" RUSTUP_MAX_RETRIES: 10 - CARGO_INCREMENTAL: 0 RUST_BACKTRACE: 1 permissions: @@ -81,6 +82,15 @@ jobs: - uses: Swatinem/rust-cache@v2 - run: cargo fmt --all --check + rustdoc: + runs-on: ubuntu-latest + needs: test + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@nightly + - uses: Swatinem/rust-cache@v2 + - run: cargo doc --no-deps + clippy: runs-on: ubuntu-latest needs: test @@ -145,6 +155,7 @@ jobs: - fuzz - msrv - outdated + - rustdoc - rustfmt - test - udeps diff --git a/crates/pica-cli/src/commands/completions.rs b/crates/pica-cli/src/commands/completions.rs index f39636f7b..e5cae97f2 100644 --- a/crates/pica-cli/src/commands/completions.rs +++ b/crates/pica-cli/src/commands/completions.rs @@ -14,8 +14,8 @@ pub(crate) struct Completions { /// Output the shell completion file for the given shell. shell: Shell, - /// Write output to instead of stdout - #[arg(short, long, value_name = "filename")] + /// Write output to FILENAME instead of stdout + #[arg(short, long, value_name = "FILENAME")] output: Option, } diff --git a/crates/pica-cli/src/commands/concat.rs b/crates/pica-cli/src/commands/concat.rs index 96cf2a99b..712a5ea6a 100644 --- a/crates/pica-cli/src/commands/concat.rs +++ b/crates/pica-cli/src/commands/concat.rs @@ -23,8 +23,8 @@ pub(crate) struct Concat { #[arg(short, long, requires = "output")] progress: bool, - /// Write simultaneously to the file and stdout - #[arg(long)] + /// Write simultaneously to the file FILENAME and stdout + #[arg(long, value_name = "FILENAME")] tee: Option, /// Whether to skip duplicate records or not. diff --git a/crates/pica-cli/src/commands/convert/mod.rs b/crates/pica-cli/src/commands/convert/mod.rs index 7d246ef73..3daa2d169 100644 --- a/crates/pica-cli/src/commands/convert/mod.rs +++ b/crates/pica-cli/src/commands/convert/mod.rs @@ -60,8 +60,8 @@ pub(crate) struct Convert { #[arg(short, long, requires = "output")] progress: bool, - /// Write output to instead of stdout - #[arg(short, long, value_name = "filename")] + /// Write output to FILENAME instead of stdout + #[arg(short, long, value_name = "FILENAME")] output: Option, /// Read one or more files in normalized PICA+ format. diff --git a/crates/pica-cli/src/commands/count.rs b/crates/pica-cli/src/commands/count.rs index 502f52a49..ed0442958 100644 --- a/crates/pica-cli/src/commands/count.rs +++ b/crates/pica-cli/src/commands/count.rs @@ -89,8 +89,8 @@ pub(crate) struct Count { #[arg(short, long, requires = "output")] progress: bool, - /// Write output to instead of stdout - #[arg(short, long, value_name = "filename")] + /// Write output to FILENAME instead of stdout + #[arg(short, long, value_name = "FILENAME")] output: Option, /// Read one or more files in normalized PICA+ format. diff --git a/crates/pica-cli/src/commands/explode.rs b/crates/pica-cli/src/commands/explode.rs index 7b8717ca9..1372e20e4 100644 --- a/crates/pica-cli/src/commands/explode.rs +++ b/crates/pica-cli/src/commands/explode.rs @@ -18,10 +18,10 @@ pub(crate) struct Explode { #[arg(long, short)] gzip: bool, - /// Limit the result to first records + /// Limit the result to first N records /// /// Note: A limit value `0` means no limit. - #[arg(long, short, value_name = "n", default_value = "0")] + #[arg(long, short, value_name = "N", default_value = "0")] limit: usize, /// A filter expression used for searching @@ -72,8 +72,8 @@ pub(crate) struct Explode { #[arg(short, long, requires = "output")] progress: bool, - /// Write output to instead of stdout - #[arg(short, long)] + /// Write output to FILENAME instead of stdout + #[arg(short, long, value_name = "FILENAME")] output: Option, /// Split a record by level (main, local, copy). diff --git a/crates/pica-cli/src/commands/filter.rs b/crates/pica-cli/src/commands/filter.rs index eb992f642..f20067c81 100644 --- a/crates/pica-cli/src/commands/filter.rs +++ b/crates/pica-cli/src/commands/filter.rs @@ -38,11 +38,11 @@ pub(crate) struct Filter { #[arg(long, short)] discard: Option, - /// Take a filter expression from + /// Take a filter expression from FILENAME /// /// Note: Do not provide an additional filter expression as an CLI /// argument! - #[arg(long = "file", short = 'F')] + #[arg(long = "file", short = 'F', value_name = "FILENAME")] expr_file: Option, /// Ignore records which are *not* explicitly listed in one of the @@ -67,10 +67,10 @@ pub(crate) struct Filter { #[arg(long = "deny-list", short = 'D')] deny: Vec, - /// Limit the result to first records + /// Limit the result to first N records /// /// Note: A limit value `0` means no limit. - #[arg(long, short, value_name = "n", default_value = "0")] + #[arg(long, short, value_name = "N", default_value = "0")] limit: usize, /// Connects the filter with additional expressions using the @@ -104,16 +104,16 @@ pub(crate) struct Filter { #[arg(long, conflicts_with = "gzip")] append: bool, - /// Write simultaneously to the file and stdout - #[arg(long, value_name = "filename", conflicts_with = "output")] + /// Write simultaneously to the file FILENAME and stdout + #[arg(long, value_name = "FILENAME", conflicts_with = "output")] tee: Option, /// Show progress bar (requires `-o`/`--output`). #[arg(short, long, requires = "output")] progress: bool, - /// Write output to instead of stdout - #[arg(short, long, value_name = "filename")] + /// Write output to FILENAME instead of stdout + #[arg(short, long, value_name = "FILENAME")] output: Option, /// A filter expression used for searching diff --git a/crates/pica-cli/src/commands/frequency.rs b/crates/pica-cli/src/commands/frequency.rs index 817c20d79..a1b7b1d30 100644 --- a/crates/pica-cli/src/commands/frequency.rs +++ b/crates/pica-cli/src/commands/frequency.rs @@ -70,20 +70,20 @@ pub(crate) struct Frequency { #[arg(long = "deny-list", short = 'D')] deny: Vec, - /// Limit result to the most frequent subfield values. + /// Limit result to the N most frequent subfield values. #[arg( long, short, - value_name = "n", + value_name = "N", hide_default_value = true, default_value = "0" )] limit: usize, - /// Ignore rows with a frequency < . + /// Ignore rows with a frequency < VALUE. #[arg( long, - value_name = "value", + value_name = "VALUE", default_value = "0", hide_default_value = true )] @@ -122,7 +122,7 @@ pub(crate) struct Frequency { #[arg(long, short)] tsv: bool, - /// Transliterate output into the selected normal form + /// Transliterate output into the selected normal form NF /// (possible values: "nfd", "nfkd", "nfc" and "nfkc"). #[arg(long = "translit", value_name = "NF")] nf: Option, @@ -131,8 +131,8 @@ pub(crate) struct Frequency { #[arg(short, long, requires = "output")] progress: bool, - /// Write output to instead of stdout. - #[arg(short, long, value_name = "filename")] + /// Write output to FILENAME instead of stdout. + #[arg(short, long, value_name = "FILENAME")] output: Option, /// Query (comma-separated list of path expressions or string diff --git a/crates/pica-cli/src/commands/hash.rs b/crates/pica-cli/src/commands/hash.rs index 6654be2c1..32f7b7725 100644 --- a/crates/pica-cli/src/commands/hash.rs +++ b/crates/pica-cli/src/commands/hash.rs @@ -31,8 +31,8 @@ pub(crate) struct Hash { #[arg(short, long, requires = "output")] progress: bool, - /// Write output to instead of stdout - #[arg(short, long)] + /// Write output to OUTPUT instead of stdout + #[arg(short, long, value_name = "OUTPUT")] output: Option, /// Read one or more files in normalized PICA+ format. If no diff --git a/crates/pica-cli/src/commands/partition.rs b/crates/pica-cli/src/commands/partition.rs index 48ab5d108..b6e3d52de 100644 --- a/crates/pica-cli/src/commands/partition.rs +++ b/crates/pica-cli/src/commands/partition.rs @@ -13,9 +13,9 @@ use crate::progress::Progress; /// Partition records by subfield values /// -/// The files are written to the directory with filenames -/// based on the values of the subfield, which is referenced by the -/// expression. +/// The files are written to the OUTDIR directory with filenames based +/// on the values of the subfield, which is referenced by the path +/// expression. /// /// If a record doesn't have the field/subfield, the record won't be /// written to a partition. A record with multiple values will be @@ -47,11 +47,11 @@ pub(crate) struct Partition { #[arg(short, long)] progress: bool, - /// Write partitions into + /// Write partitions into OUTDIR /// /// If the directory doesn't exists, it will be created /// automatically. - #[arg(long, short, value_name = "outdir", default_value = ".")] + #[arg(long, short, value_name = "OUTDIR", default_value = ".")] outdir: PathBuf, /// Filename template ("{}" is replaced by subfield value) diff --git a/crates/pica-cli/src/commands/print.rs b/crates/pica-cli/src/commands/print.rs index 472730aaf..e331073b2 100644 --- a/crates/pica-cli/src/commands/print.rs +++ b/crates/pica-cli/src/commands/print.rs @@ -16,11 +16,11 @@ pub(crate) struct Print { #[arg(short, long)] skip_invalid: bool, - /// Limit the result to first records - #[arg(long, short, value_name = "n", default_value = "0")] + /// Limit the result to first N records + #[arg(long, short, value_name = "N", default_value = "0")] limit: usize, - /// Transliterate output into the selected normal form + /// Transliterate output into the selected normal form NF #[arg(long = "translit", value_name = "NF")] nf: Option, @@ -28,8 +28,8 @@ pub(crate) struct Print { #[arg(short, long, requires = "output")] progress: bool, - /// Write output to instead of stdout - #[arg(short, long, value_name = "filename")] + /// Write output to FILENAME instead of stdout + #[arg(short, long, value_name = "FILENAME")] output: Option, /// Read one or more files in normalized PICA+ format. diff --git a/crates/pica-cli/src/commands/sample.rs b/crates/pica-cli/src/commands/sample.rs index d8af55201..0eda7a6e0 100644 --- a/crates/pica-cli/src/commands/sample.rs +++ b/crates/pica-cli/src/commands/sample.rs @@ -26,7 +26,7 @@ pub(crate) struct Sample { #[arg(short, long, requires = "output")] progress: bool, - /// Write output to instead of stdout + /// Write output to FILENAME instead of stdout #[arg(short, long, value_name = "filename")] output: Option, diff --git a/crates/pica-cli/src/commands/select.rs b/crates/pica-cli/src/commands/select.rs index f486f0291..5962cc0c6 100644 --- a/crates/pica-cli/src/commands/select.rs +++ b/crates/pica-cli/src/commands/select.rs @@ -63,7 +63,7 @@ pub(crate) struct Select { #[arg(long, short)] tsv: bool, - /// Transliterate output into the selected normal form + /// Transliterate output into the selected normal form NF /// (possible values: "nfd", "nfkd", "nfc" and "nfkc") #[arg(long = "translit", value_name = "NF")] nf: Option, @@ -76,10 +76,10 @@ pub(crate) struct Select { #[arg(long)] append: bool, - /// Limit the result to first records (not rows!) + /// Limit the result to first N records (not rows!) /// /// Note: A limit value `0` means no limit. - #[arg(long, short, value_name = "n", default_value = "0")] + #[arg(long, short, value_name = "N", default_value = "0")] limit: usize, /// A filter expression used for searching @@ -133,8 +133,8 @@ pub(crate) struct Select { #[arg(short, long, requires = "output")] progress: bool, - /// Write output to instead of stdout - #[arg(short, long, value_name = "filename")] + /// Write output to FILENAME instead of stdout + #[arg(short, long, value_name = "FILENAME")] output: Option, /// Query (comma-separated list of path expressions or string diff --git a/crates/pica-cli/src/commands/slice.rs b/crates/pica-cli/src/commands/slice.rs index b90c714a7..f763c6cae 100644 --- a/crates/pica-cli/src/commands/slice.rs +++ b/crates/pica-cli/src/commands/slice.rs @@ -71,8 +71,8 @@ pub(crate) struct Slice { #[arg(short, long, requires = "output")] progress: bool, - /// Write output to instead of stdout - #[arg(short, long, value_name = "filename")] + /// Write output to FILENAME instead of stdout + #[arg(short, long, value_name = "FILENAME")] output: Option, /// Read one or more files in normalized PICA+ format diff --git a/crates/pica-cli/src/commands/split.rs b/crates/pica-cli/src/commands/split.rs index 74ea5f9e2..ff268f6cb 100644 --- a/crates/pica-cli/src/commands/split.rs +++ b/crates/pica-cli/src/commands/split.rs @@ -30,7 +30,7 @@ pub(crate) struct Split { #[arg(short, long)] progress: bool, - /// Write partitions into + /// Write partitions into OUTDIR #[arg(long, short, value_name = "outdir", default_value = ".")] outdir: PathBuf,