rustdoc: accept --out-dir and soft-deprecate --output

[jyn514]

Rustc uses --out-dir, but rustdoc rejects it. This is an unnecessary incompatibility; rustdoc should accept --out-dir too. Accepting --output was a mistake, but it's stable and used in almost literally every run by cargo, so we realistically can't even warn on it. We should document that --out-dir is the recommended option, though.

Once --out-dir has been accepted for several releases, we could consider starting to warn on --output, but I don't suggest committing to that now.

[jyn514]

@rfcbot fcp merge

[rfcbot]

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

• @CraftSpider
• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @camelid
• @jsha
• @jyn514
• @ollie27

Concerns:

• churn resolved by rustdoc: accept --out-dir and soft-deprecate --output #91260 (comment)
• consistency with rustc resolved by rustdoc: accept --out-dir and soft-deprecate --output #91260 (comment)

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.

[jyn514]

Note that this will still leave an inconsistency - rustdoc will treat -o as a synonym for --out-dir, while rustc treats -o as a filename and not a directory. This isn't great for modes where it makes sense to output a single file, such as --output-format json. I think it's still better than the current situation though (where -o is a synonym for --output).

[Manishearth]

@rfcbot reviewed

[rfcbot]

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

[jyn514]

Mentoring instructions:

1. Add a new out-dir option in src/librustdoc/lib.rs.
2. Change the output option to point to out-dir:

   rust/src/librustdoc/lib.rs

   Line 281 in 686e313

   stable("o", |o| o.optopt("o", "output", "where to place the output", "PATH")),

Feel free to ask for help, but please do so on Zulip or Discord to avoid pinging the whole team :)

[0xPoe]

@rustbot claim

[camelid]

@rfcbot concern consistency with rustc
@rfcbot concern churn

My understanding is that the purpose of this proposal is to increase consistency with rustc. However, I would like to ensure that (1) the new behavior is fully consistent with rustc and (2) the churn and potential confusion of having --output and --out-dir be synonyms is worth it.

For example, rustc prefers -o over --out-dir; if both are passed, it emits this warning:

warning: ignoring --out-dir flag due to -o flag

I would like to make sure—perhaps by discussing with T-compiler—that making this change won't add more inconsistency.

With regards to churn, it seems potentially confusing to have both --output and --out-dir, even though they're synonyms. For example, if we change our documentation to only discuss --out-dir, existing users—and maintainers—could feel confused about whether --out-dir is a new option or just an alias. Granted, most users of rustdoc are probably using it through cargo or docs.rs, so perhaps this isn't an issue.

Overall, I do think this is a good change, but since there hasn't been much discussion about the full implications of this change, I would like to make sure we don't accidentally introduce more inconsistency. So, I would just like to have a bit more discussion about this before we merge it.

---

Note that this will still leave an inconsistency - rustdoc will treat -o as a synonym for --out-dir, while rustc treats -o as a filename and not a directory. This isn't great for modes where it makes sense to output a single file, such as --output-format json.

In the case of --output-format json, IIRC it currently outputs a doc/ folder with a file in it, not a freestanding file.

[jyn514]

if both are passed, it emits this warning:
warning: ignoring --out-dir flag due to -o flag

I think the better comparison is passing --out-dir twice:

rustc src/lib.rs --out-dir target --out-dir target --crate-type lib
error: Option 'out-dir' given more than once

Recall that in rustdoc, -o is a synonym for --output.

I would like to make sure—perhaps by discussing with T-compiler—that making this change won't add more inconsistency.

I'm ok with doing this, but I don't know what inconsistency you're worried about. Can you be in charge of asking T-compiler about this?

With regards to churn, it seems potentially confusing to have both --output and --out-dir, even though they're synonyms. For example, if we change our documentation to only discuss --out-dir, existing users—and maintainers—could feel confused about whether --out-dir is a new option or just an alias.

I'm not suggesting we remove any existing documentation, only document that --output is a synonym for --out-dir. You can look at #91310 if you'd like to see the concrete changes.

In the case of --output-format json, IIRC it currently outputs a doc/ folder with a file in it, not a freestanding file.

Right - I'm saying if I didn't know the existing behavior, I would expect --output-format json -o my_file.json to create a file named .json, not a directory with a file in it.

[camelid]

I think I won't have enough time in the near future to manage discussing this with T-compiler. I don't feel strongly about this change in either direction, but it seems okay, and I don't want to block it since the rest of the team has signed off.

@rfcbot resolve consistency with rustc
@rfcbot resolve churn
@rfcbot reviewed

[rfcbot]

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

[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.

[jyn514]

Added in #91310.