type impl,buck2 link,extern-html-root-url,period

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

Author: EtomicBomb

text/0000-mergeable-rustdoc-cross-crate-info.md

@@ -261,7 +261,7 @@ Use `--merge=read-write`, and specify the same `--out-dir` to every invocation o
 
 ### Cross-crate information, no shared directory
 
-Specify a different `--out-dir` to every invocation of rustdoc. Additionally, you should provide `--write-info-json=<crate-specific path to file>` and `--merge=none` when documenting the dependencies of your root crate. Then, when you document the root crate, you will provide  `--include-info-json=<crate-specific path selected previously>`, `--include-rendered-docs=<out dirs chosen previously>` for each one of your dependencies, and `--merge=write-only`. You should provide `--extern-html-root-url`, and specify a static, absolute location for the URL. This flag, with the same URL, will be needed for every invocation of rustdoc, for every dependency.
+Specify a different `--out-dir` to every invocation of rustdoc. Additionally, you should provide `--write-info-json=<path to crate-specific file>` and `--merge=none` when documenting the dependencies of your root crate. Then, when you document the root crate, you will provide  `--include-info-json=<crate-specific path selected previously>`, `--include-rendered-docs=<out dirs chosen previously>` for each one of your dependencies, and `--merge=write-only`. You should provide `--extern-html-root-url`, and specify a static, absolute location for the URL. This flag, with the same URL, will be needed for every invocation of rustdoc, for every dependency.
 
 # Reference-level explanation
 
@@ -332,8 +332,8 @@ This RFC does not alter previous compatibility guarantees made about the output
 In the same way that the [rustdoc HTML output is unstable](https://rust-lang.github.io/rfcs/2963-rustdoc-json.html#:~:text=The%20HTML%20output%20of%20rustdoc,into%20a%20different%20format%20impractical), the content of `crate-info.json` will be considered unstable. Between versions of rustdoc, breaking changes to the content of `crate-info.json` should be expected. Only the presence of a `crate-info.json` file is promised, under `--write-info-json`. Merging cross-crate information generated by disparate versions of rustdoc is not supported. To detect whether `crate-info.json` is compatible, rustdoc includes a version number in these files (see New file: `crate-info.json`).
 
 The implementation of the RFC itself is designed to produce only minimal changes to cross-crate info files and the HTML output of rustdoc. Exhaustively, the implementation is allowed to 
-* Change the sorting order of trait implementations, type implementations, and other cross-crate info in the HTML output of rustdoc
-* Add a comment on the last line of generated HTML pages, to store metadata relevant to appending items to them
+* Change the sorting order of trait implementations, type implementations, and other cross-crate info in the HTML output of rustdoc.
+* Add a comment on the last line of generated HTML pages, to store metadata relevant to appending items to them.
 * Refactor the JavaScript contents of cross-crate information files, in ways that do not change their overall behavior. If the JavaScript fragment declared an array called `ALL_CRATES` with certain contents, it will continue to do so.
 
 Changes this minimal are intended to avoid breaking tools that use the output of rustdoc, like Cargo, docs.rs, and rustdoc's JavaScript frontend, in the near-term. Going forward, rustdoc will not make formal guarantees about the content of cross-crate info files.
@@ -365,7 +365,7 @@ There is an [open issue](https://github.com/bazelbuild/rules_rust/issues/1837) r
 
 ## Buck2
 
-The Buck2 build system has rules for building and testing rust binaries and libraries. <https://buck2.build/docs/api/rules/#rust_library>
+The Buck2 build system has rules for building and testing rust binaries and libraries. <https://buck2.build/docs/prelude/globals/#rust_library>
 
 It has a subtarget, `[doc]`, for generating rustdoc for a crate.
 
@@ -405,11 +405,13 @@ This proposal proposes to continue reading from the rendered cross-crate informa
 
 ## Item links?
 
-Require users to pass `--extern-html-root-url` on all external dependencies (current), vs. add a new flag to facilitate missing docs links being generated across all user crates (should consider)
+Require users to pass `--extern-html-root-url` on all external dependencies (current), vs. add a new flag to facilitate missing docs links being generated across all user crates (should consider).
 
-Cross-crate links are an important consideration when merging documentation. rustdoc provides a flag, `--extern-html-root-url`, which can provide fine-grain control over the generated URL for documentation. We believe this is already sufficient for generating cross-crate links, and we will make no changes to the generation of item links. Example usage of this flag is in the Guide-level explanation.
+For the purpose of generating cross-crate links, rustdoc classifies the location of crates as external, local, or unknown (relative to the crate in the current invocation of rustdoc). Local crates are the crates that share the same `--out-dir`. External crates have documentation that could not be found in the current `--out-dir`, but otherwise have a known location. Item links are not generated to crates with an unknown location. When the `--extern-html-root-url=<crate name>=<url>` flag is provided, an otherwise unknown crate `<crate name>` becomes an externally located crate, forcing it to generate item links.
 
-A proposal is to provide more options to facilitate cross-crate links. For example, we could add a flag that implies `--extern-html-root-url` and `--include-info-json` on all crates passed through `--extern`. It could be something like `--extern-html-root-url-all-user-crates`. User crates would be taken to mean the transitive dependencies of the current crate, excluding the standard library. This is complicated by things like <https://doc.rust-lang.org/cargo/reference/unstable.html#build-std>.
+This is of relevance to this proposal, because users who document crates with separate `--out-dir`s may still expect cross-crate links to work. Currently, `--extern-html-root-url` is the exclusive mechanism for specifying link destinations for crates who would otherwise have an unknown location. We will expect users to provide `--extern-html-root-url` for all direct dependencies of a crate they are documenting. Example usage of this flag is in the Guide-level explanation.
+
+A proposal is to provide more options to facilitate cross-crate links. For example, we could add a flag that implies `--extern-html-root-url`, with a fixed location, to all crates passed through `--extern`. User crates would be taken to mean the transitive dependencies of the current crate, excluding the standard library.
 
 ## Reuse existing option?
 
@@ -427,10 +429,10 @@ We could also leave it as-is: always false unless we're scraping examples, and g
 
 # Future possibilities
 
-This change could begin to facilitate type aliases and the trait aliases being
+This change could begin to facilitate trait implementations being
 statically compiled as part of the .html documentation, instead of being loaded
-as separate JavaScript files. Each type and trait alias could be stored as an
-HTML part, which are then merged into the regular documentation.
+as separate JavaScript files. Each trait implementation could be stored as an
+HTML part, which are then merged into the regular documentation. Implementations of traits on type aliases should remain separate, as they serve as a [size hack](https://github.com/rust-lang/rust/pull/116471).
 
 Another possibility is for `doc.parts` to be distributed on `docs.rs` along with the regular documentation. This would facilitate a mode where documentation of the dependencies could be downloaded externally, instead of being rebuilt locally.