From c431f8c29a41413dddcb3bfa0d71c9cabe366317 Mon Sep 17 00:00:00 2001 From: Camelid Date: Sun, 28 Feb 2021 11:21:01 -0800 Subject: [PATCH] Cleanup rustdoc chapters a bit * Rename "The walking tour of rustdoc" to "Rustdoc overview", which I think is a more accurate name * Use same name in sidebar TOC as in chapter text * Make links between the two chapters prominent * Convert a few `.html` links to `.md` Probably we should just merge the chapters, but leaving that for later. --- src/SUMMARY.md | 4 ++-- src/rustdoc-internals.md | 2 +- src/rustdoc.md | 15 ++++++--------- 3 files changed, 9 insertions(+), 12 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 02e8e3843f3c5..056ff050f892f 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -13,7 +13,7 @@ - [Suggested Workflows](./building/suggested.md) - [Distribution artifacts](./building/build-install-distribution-artifacts.md) - [Documenting Compiler](./building/compiler-documenting.md) - - [Rustdoc](./rustdoc.md) + - [Rustdoc overview](./rustdoc.md) - [ctags](./building/ctags.md) - [Adding a new target](./building/new-target.md) - [The compiler testing framework](./tests/intro.md) @@ -63,7 +63,7 @@ - [Memory Management in Rustc](./memory.md) - [Serialization in Rustc](./serialization.md) - [Parallel Compilation](./parallel-rustc.md) -- [Rustdoc](./rustdoc-internals.md) +- [Rustdoc internals](./rustdoc-internals.md) # Source Code Representation diff --git a/src/rustdoc-internals.md b/src/rustdoc-internals.md index 3e950a0eb85ae..b2dc2f7fd1e63 100644 --- a/src/rustdoc-internals.md +++ b/src/rustdoc-internals.md @@ -3,7 +3,7 @@ This page describes rustdoc's passes and modes. For an overview of rustdoc, -see [`rustdoc`](./rustdoc.md). +see the ["Rustdoc overview" chapter](./rustdoc.md). ## From crate to clean diff --git a/src/rustdoc.md b/src/rustdoc.md index c087689d9b43a..33f2c5f357194 100644 --- a/src/rustdoc.md +++ b/src/rustdoc.md @@ -1,17 +1,20 @@ -# The walking tour of rustdoc +# Rustdoc overview Rustdoc actually uses the rustc internals directly. It lives in-tree with the compiler and standard library. This chapter is about how it works. For information about Rustdoc's features and how to use them, see the [Rustdoc book](https://doc.rust-lang.org/nightly/rustdoc/). +For more details about how rustdoc works, see the ["Rustdoc internals" chapter]. + +["Rustdoc internals" chapter]: ./rustdoc-internals.md Rustdoc is implemented entirely within the crate [`librustdoc`][rd]. It runs the compiler up to the point where we have an internal representation of a crate (HIR) and the ability to run some queries about the types of items. [HIR] and [queries] are discussed in the linked chapters. -[HIR]: ./hir.html -[queries]: ./query.html +[HIR]: ./hir.md +[queries]: ./query.md [rd]: https://github.com/rust-lang/rust/tree/master/src/librustdoc `librustdoc` performs two major steps after that to render a set of @@ -59,9 +62,3 @@ does is call the `main()` that's in this crate's `lib.rs`, though.) * Tests on search index generation are located in `src/test/rustdoc-js`, as a series of JavaScript files that encode queries on the standard library search index and expected results. - -## See also - -For more details about how rustdoc works, see the page on [rustdoc internals]. - -[rustdoc internals]: ./rustdoc-internals.md