Add - (stdin) support in rustdoc

[Urgau]

This PR adds support for the special - input which threats the input as coming from stdin instead of being a filepath.

Doing this also makes rustdoc consistent with rustc and every other tools. Full motivation.

Fixes #123671
r? @fmease

[rustbot]

The run-make-support library was changed

cc @jieyouxu

Some changes occurred in run-make tests.

cc @jieyouxu

[fmease]

Thanks, that's phenomenal! I have some small suggestions and questions.
Looks good overall but ofc, let's wait for the “rmake stdin” PR of yours that you mentioned. After that I'm gonna ping T-rustdoc and ask them for a FCP-merge.

[fmease]

Ofc, technically technically technically speaking this constitutes a breaking change but that's only theoretical in nature. On *nix systems, ppl can name their files -. This PR would break the following:

# Create a file called `-`:
printf 'pub fn omg() {}' > -
# Yes, we've just created a file called `-`.
# On the command-line, run the following to see the output:
< -
# Now document our wonderful crate:
rustdoc - --crate-name dash
# Docs were generated:
"$BROWSER" ./doc/dash/index.html

[fmease]

Hey there @rust-lang/rustdoc, I propose merging this¹ after an FCP.

This PR updates rustdoc's CLI to recognize the INPUT argument - (dash) as instructing rustdoc to read the source code from STDIN instead of from a path. Apart from the fact that this is a common CLI convention, it's also consistent with rustc's CLI.

Motivation:

1. Consistency with rustc's CLI
2. Doing what is expected from CLI applications
3. Enabling power users of the rustdoc CLI (i.e., rustdoc & rustc devs)
   • to very quickly check if rustdoc accepts certain source code and/or
   • to rapidly generate docs for small snippets
   • for example during a rustdoc meeting where time is key
   • demo:
     1. $ printf 'pub fn f() -> impl Iterator { 0 }' | rustdoc -
     2. "Oh wow, rustdoc accepts this code..."
     3. "...wait — sanity check — rustc hopefully 🤞 doesn't accept that..."
     4. ↑←←←BSBS a.k.a. $ printf 'pub fn f() -> impl Iterator { 0 }' | rustc -
     5. "Indeed 😌, it doesn't"
     6. "Ah yes, now I remember ... rustdoc doesn't run all of rustc's semantic analysis steps, all good"

Maintenance Cost: Very low (next to zero)
Impact: Low

Potential Concerns:

1. (negligible) It's technically speaking a breaking change on *nix systems. See my comment above
2. At least on *nix systems (and by extension in WSL), you can already express this, so this new minor feature “doesn't gain us anything”.
   • E.g., printf 'pub fn f() {}' | rustdoc /dev/stdin (sh)
   • E.g., rustdoc <(printf 'pub fn f() {}') (sh)
   • However,
     • these alternatives are more verbose & obscure and
     • they don't work on Windows (outside of WSL) as far as I'm aware (I'm not a Windows dev, so I don't know the specifics)

Footnotes

1. Modulo some smaller tweaks to the docs & the impl. See my latest review comments. ↩

[Manishearth]

I think we should land this, and I'm surprised this wasn't previously supported

[GuillaumeGomez]

I'm also surprised it's not already there. Let's start the FCP then.

@rfcbot fcp merge

[rfcbot]

Team member @GuillaumeGomez has proposed to merge this. The next step is review by the rest of the tagged team members:

• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @aDotInTheVoid
• @camelid
• @jsha
• @notriddle

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[riking]

re alternatives: If someone is actually putting source code in a file named -, you can still operate on it by making a path relative to the current directory: rustdoc ./- or rustdoc .\-.

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[GuillaumeGomez]

Thanks everyone!

@bors r+

[bors]

📌 Commit 7e1dc74 has been approved by GuillaumeGomez

It is now in the queue for this repository.

[bors]

⌛ Testing commit 7e1dc74 with merge bb97203...

[bors]

☀️ Test successful - checks-actions
Approved by: GuillaumeGomez
Pushing bb97203 to master...

[rust-timer]

Finished benchmarking commit (bb97203): comparison URL.

Overall result: no relevant changes - no action needed

@rustbot label: -perf-regression

Instruction count

This benchmark run did not return any relevant results for this metric.

Max RSS (memory usage)

This benchmark run did not return any relevant results for this metric.

Cycles

Results (primary -4.1%)

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-4.1%	[-4.1%, -4.1%]	1
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	-4.1%	[-4.1%, -4.1%]	1

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 667.741s -> 668.952s (0.18%)
Artifact size: 316.07 MiB -> 316.33 MiB (0.08%)

[ojeda]

Thanks for this :)