jyn514 commented 15 days ago

@rfcbot fcp merge

rfcbot commented 15 days ago •

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

Concerns:

• churn resolved by #91260 (comment)
• consistency with rustc resolved by #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 commented 15 days ago

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 commented 15 days ago

@rfcbot reviewed

rfcbot commented 14 days ago

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

jyn514 commented 14 days ago

Mentoring instructions:

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

   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 :)

hi-rustin commented 14 days ago

@rustbot claim

camelid commented 13 days ago

@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 commented 13 days ago •

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 commented 12 days ago

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 commented 12 days ago

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

rfcbot commented 2 days ago

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 commented 4 hours ago •

Added in #91310.