target.<triple>.rustdocflags is undocumented and buggy

[Nemo157]

Problem

It is possible to pass target-specific rustdocflags via config-environment-variables:

> CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUSTDOCFLAGS=--bar cargo doc
 Documenting foo v0.1.0 (/tmp/scratch.rust-unwrapped.2023-12-21T12-52.BcbaxB/foo)
error: Unrecognized option: 'bar'

error: could not document `foo`

Caused by:
  process didn't exit successfully: `rustdoc --edition=2021 --crate-type bin --crate-name foo src/main.rs -o /run/user/1000/cargo-home/target/shared/doc --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat --diagnostic-width=201 --document-private-items '-Arustdoc::private-intra-doc-links' -C metadata=7eced6d5673aa97d -L dependency=/run/user/1000/cargo-home/target/shared/debug/deps --bar --crate-version 0.1.0` (exit status: 1)

Trying to pass it via --config doesn't work, it seems to believe it must simultaneously be both a table and a string/array-of-strings:

> cargo doc --config 'target.x86_64-unknown-linux-gnu.rustdocflags="--some-flag"'
error: expected a table, but found a string for `target.x86_64-unknown-linux-gnu.rustdocflags` in --config cli option

> cargo doc --config 'target.x86_64-unknown-linux-gnu.rustdocflags.foo="--some-flag"'
error: invalid configuration for key `target.x86_64-unknown-linux-gnu.rustdocflags`
expected a string or array of strings, but found a table for `target.x86_64-unknown-linux-gnu.rustdocflags` in --config cli option

Using .cargo/config.toml behaves the same as --config.

It is also not mentioned at all under https://doc.rust-lang.org/nightly/cargo/reference/config.html#target

Steps

No response

Possible Solution(s)

No response

Notes

No response

Version

cargo 1.76.0-nightly (978722961 2023-12-06)
release: 1.76.0-nightly
commit-hash: 9787229614b27854cf73d57ffae430d7c1e6caa4
commit-date: 2023-12-06
host: x86_64-unknown-linux-gnu
libgit2: 1.7.1 (sys:0.18.1 vendored)
libcurl: 8.4.0-DEV (sys:0.4.68+curl-8.4.0 vendored ssl:OpenSSL/1.1.1u)
ssl: OpenSSL 1.1.1u  30 May 2023
os: NixOS 23.11.0 [64-bit]

[weihanglo]

Oops I wrote a false claim there:

cargo/src/cargo/core/compiler/build_context/target_info.rs

Lines 809 to 811 in a9c749c

	// `target.cfg(…).rustdocflags` is currently not supported.
	// In fact, neither is `target.<triple>.rustdocflags`.
	Flags::Rustdoc => None,

Given that is accidentally supported, shoud we just make it a feature and document it?