docs: Fix rustdoc warnings (#889)

Signed-off-by: Nico Wagner <[email protected]>

.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

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 <filename> instead of stdout
-    #[arg(short, long, value_name = "filename")]
+    /// Write output to FILENAME instead of stdout
+    #[arg(short, long, value_name = "FILENAME")]
     output: Option<OsString>,
 }
 

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 <TEE> and stdout
-    #[arg(long)]
+    /// Write simultaneously to the file FILENAME and stdout
+    #[arg(long, value_name = "FILENAME")]
     tee: Option<OsString>,
 
     /// Whether to skip duplicate records or not.

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 <filename> instead of stdout
-    #[arg(short, long, value_name = "filename")]
+    /// Write output to FILENAME instead of stdout
+    #[arg(short, long, value_name = "FILENAME")]
     output: Option<OsString>,
 
     /// Read one or more files in normalized PICA+ format.

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 <filename> instead of stdout
-    #[arg(short, long, value_name = "filename")]
+    /// Write output to FILENAME instead of stdout
+    #[arg(short, long, value_name = "FILENAME")]
     output: Option<OsString>,
 
     /// Read one or more files in normalized PICA+ format.

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 <n> 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 <OUTPUT> instead of stdout
-    #[arg(short, long)]
+    /// Write output to FILENAME instead of stdout
+    #[arg(short, long, value_name = "FILENAME")]
     output: Option<OsString>,
 
     /// Split a record by level (main, local, copy).

crates/pica-cli/src/commands/filter.rs

@@ -38,11 +38,11 @@ pub(crate) struct Filter {
     #[arg(long, short)]
     discard: Option<String>,
 
-    /// Take a filter expression from <EXPR_FILE>
+    /// 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<PathBuf>,
 
     /// 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<PathBuf>,
 
-    /// Limit the result to first <n> 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 <filename> 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<PathBuf>,
 
     /// Show progress bar (requires `-o`/`--output`).
     #[arg(short, long, requires = "output")]
     progress: bool,
 
-    /// Write output to <filename> instead of stdout
-    #[arg(short, long, value_name = "filename")]
+    /// Write output to FILENAME instead of stdout
+    #[arg(short, long, value_name = "FILENAME")]
     output: Option<OsString>,
 
     /// A filter expression used for searching

crates/pica-cli/src/commands/frequency.rs

@@ -70,20 +70,20 @@ pub(crate) struct Frequency {
     #[arg(long = "deny-list", short = 'D')]
     deny: Vec<PathBuf>,
 
-    /// Limit result to the <n> 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 < <value>.
+    /// 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 <NF>
+    /// Transliterate output into the selected normal form NF
     /// (possible values: "nfd", "nfkd", "nfc" and "nfkc").
     #[arg(long = "translit", value_name = "NF")]
     nf: Option<NormalizationForm>,
@@ -131,8 +131,8 @@ pub(crate) struct Frequency {
     #[arg(short, long, requires = "output")]
     progress: bool,
 
-    /// Write output to <filename> instead of stdout.
-    #[arg(short, long, value_name = "filename")]
+    /// Write output to FILENAME instead of stdout.
+    #[arg(short, long, value_name = "FILENAME")]
     output: Option<OsString>,
 
     /// Query (comma-separated list of path expressions or string

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 <OUTPUT> instead of stdout
-    #[arg(short, long)]
+    /// Write output to OUTPUT instead of stdout
+    #[arg(short, long, value_name = "OUTPUT")]
     output: Option<OsString>,
 
     /// Read one or more files in normalized PICA+ format. If no

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 <outdir> directory with filenames
-/// based on the values of the subfield, which is referenced by the
-/// <PATH> 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 <outdir>
+    /// 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)

crates/pica-cli/src/commands/print.rs

@@ -16,20 +16,20 @@ pub(crate) struct Print {
     #[arg(short, long)]
     skip_invalid: bool,
 
-    /// Limit the result to first <n> 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 <NF>
+    /// Transliterate output into the selected normal form NF
     #[arg(long = "translit", value_name = "NF")]
     nf: Option<NormalizationForm>,
 
     /// Show progress bar (requires `-o`/`--output`).
     #[arg(short, long, requires = "output")]
     progress: bool,
 
-    /// Write output to <filename> instead of stdout
-    #[arg(short, long, value_name = "filename")]
+    /// Write output to FILENAME instead of stdout
+    #[arg(short, long, value_name = "FILENAME")]
     output: Option<OsString>,
 
     /// Read one or more files in normalized PICA+ format.

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 <filename> instead of stdout
+    /// Write output to FILENAME instead of stdout
     #[arg(short, long, value_name = "filename")]
     output: Option<OsString>,
 

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 <NF>
+    /// Transliterate output into the selected normal form NF
     /// (possible values: "nfd", "nfkd", "nfc" and "nfkc")
     #[arg(long = "translit", value_name = "NF")]
     nf: Option<NormalizationForm>,
@@ -76,10 +76,10 @@ pub(crate) struct Select {
     #[arg(long)]
     append: bool,
 
-    /// Limit the result to first <n> 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 <filename> instead of stdout
-    #[arg(short, long, value_name = "filename")]
+    /// Write output to FILENAME instead of stdout
+    #[arg(short, long, value_name = "FILENAME")]
     output: Option<OsString>,
 
     /// Query (comma-separated list of path expressions or string

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 <filename> instead of stdout
-    #[arg(short, long, value_name = "filename")]
+    /// Write output to FILENAME instead of stdout
+    #[arg(short, long, value_name = "FILENAME")]
     output: Option<OsString>,
 
     /// Read one or more files in normalized PICA+ format

crates/pica-cli/src/commands/split.rs

@@ -30,7 +30,7 @@ pub(crate) struct Split {
     #[arg(short, long)]
     progress: bool,
 
-    /// Write partitions into <outdir>
+    /// Write partitions into OUTDIR
     #[arg(long, short, value_name = "outdir", default_value = ".")]
     outdir: PathBuf,