cargo-rustdoc: `error: too many file operands` when experimental feature `-w` is passed without parameters

[NovaliX-Dev]

When i try to run this command : cargo +nightly rustdoc -- -Z unstable-options -w

Rustdoc returns this error :

error: too many file operands

Which confuses me. I mean, i didn't passed any file format, so how can there be too many of them ?

We should have a clearer error, something like this :

error: no output format given after `-w`

[fmease]

While cargo rustdoc comes from a different repository (namely https://github.com/rust-lang/cargo), the rustdoc binary does bear the blame here:

So, assuming the package contains a library crate, Cargo executes the following command (manually adjusted for legibility):

rustdoc --edition=2021 --crate-type lib --crate-name "$CRATE_NAME" src/lib.rs \
    -o "$CARGO_TARGET_DIR/doc" --check-cfg 'cfg(docsrs)' --check-cfg 'cfg(feature, values())' \
    --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat --diagnostic-width=192 \
    -C metadata=$DATA -L "dependency=$CARGO_TARGET_DIR/debug/deps" \
    -Z unstable-options -w --crate-version "$CRATE_VERSION"

Now, as you can see, Cargo passes extra arguments after -w which should've been fine but here's the kicker: For some reason, rustdoc/getopts tries to parse the argument for -w greedily or verbatim. Meaning that it considers the string --crate-version to be the argument for -w (!) instead of its own separate flag (and -w's arg to be none or empty)¹. As a result of a that, the crate version "$CRATE_VERSION" (e.g., 0.1.0) gets interpreted as a stray file operand (top-level argument). Hence the error too many file operands (it sees src/lib.rs and "$CRATE_VERSION").

If possible (getopts is quite primitive), the fix would be not to parse the argument of -w so greedily. This should lead to the error changing to error: Argument to option 'w' missing.

Footnotes

1. Cf: rustdoc f.rs -Zunstable-options -w --verbose leads to error: unknown output format `--verbose` . ↩

[fmease]

For some reason, rustdoc/getopts tries to parse the argument for -w greedily or verbatim

I've just noticed this seems to affect all "argument-taking" flags, e.g. --crate-version --verbose literally sets the crate version to --verbose. Oh no, getopts >:(

[fmease]

Switching getopt's parsing style from FloatingFrees to StopAtFirstFree is not what we want.

Ah, I think we want to update all references of .optopt(…) to .optflagopt(…) and (I guess) manually reject .opt_str("…") == None, though one needs to double-check what other consequences that would have and if it would be a breaking change (if it leads to fewer or more program invocations getting accepted). Hmm, that doesn't work either lol >.< It would lead to -w getting accepted as if it wasn't passed at all (None). Oh, this is annoying.

[GuillaumeGomez]

Seems like a fix is required in getopts. Something like:

enum ArgumentStatus<T> {
    // `T` is the value, so if `None`, then we can emit the right error message
    Present(T),
    NotPresent.
}

maybe?

[NovaliX-Dev]

For single-use arguments that seems to be something that can be tested.

We still need to take into account multiple-use arguments (arguments that can be used multiple times) though. I don't know if getopts support them.

[GuillaumeGomez]

Well, if it doesn't support it, might be worth adding it. :)