Skip to content

Commit

Permalink
Cleanup rustdoc chapters a bit
Browse files Browse the repository at this point in the history
* 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.
  • Loading branch information
camelid authored and Joshua Nelson committed Feb 28, 2021
1 parent 3cdb245 commit c431f8c
Show file tree
Hide file tree
Showing 3 changed files with 9 additions and 12 deletions.
4 changes: 2 additions & 2 deletions src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion src/rustdoc-internals.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
<!-- toc -->

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

Expand Down
15 changes: 6 additions & 9 deletions src/rustdoc.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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

0 comments on commit c431f8c

Please sign in to comment.