RFC 3662: Mergeable rustdoc cross-crate info #3699
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
fixed broken buck2 link, address notriddle's comment about trait vs type impls, adds period at ends of sentence that are missing periods, and adds clarification about the usefulness of extern-html-root-url
* Rename --merge=none|read-write|write-only to --merge=none|shared|finalize * --write-info-json=target/doc.parts/my-crate/crate-info.json -> --parts-out-dir=target/doc.parts/my-crate * --include-info-json=target/doc.parts/my-crate/crate-info.json -> --include-parts-dir=target/doc.parts/my-crate * Clarify the three modes / workflows in the text of the RFC
I moved the section discussing --extern-html-root-url from unresolved questions to the Reference-level explanation, as there have been no proposals discussing alternatives. I removed the section about no_emit_shared in unresolved questions, because it has not come up in discussion and no_emit_shared was never a command line option anyway. The names proposed in discussion are better and more declarative suggestions
* Explain default behavior of rustdoc in Reference-level explanation * Flag summary in Guide-level explanation * Say that crate-info.json is stable because build systems need to rely on it * t,s,i -> trait-crate, struct-crate, index-crate * T, S -> Trait, Struct
* Remove the --include-rendered-docs flag * --parts-out-dir restricted to --merge=none * --include-parts-dir restricted to --merge=finalize * crate-info.json -> crate-info to emphasize opaqueness * doc.parts contents edition stability promises are replaced with a statement saying that rustdoc will make an reasonable effort to continue just having crate-info files
* New directory: `doc.parts/<crate-name>/crate-info` -> New directory: `doc.parts`. * Number of times `--parts-out-dir`, `--merge`, and `--include-parts-dir` can be provided are mentioned. * Describe why `doc.parts` is a directory. * Description of multiple parallel invocations of rustdoc. * Describe why to run rustc before rustdoc. * Fix typos.
* remove 'Unresolved: index crate?' from the unresolved questions section * remove the requirement on the index crate from various sections
typo in --merge=finalize description: can links
* full sentences in intro * Clarify Cargo's expected use of `--merge=none|shared|finalize` * Explain why you would use multiple rustdoc invocations with the same --out-dir and merge=none * Remove justification for why rustdoc output can be unstable in general * Permalink specific fuchsia commit
Change sentence reading "The WIP may change the sorting order..." to "The implementation may change the sorting order..." Co-authored-by: Noah Lev <camelidcamel@gmail.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
See #3662 for the actual RFC, by @EtomicBomb. This PR is just for merging purposes.
Rendered