Skip to content

Commit

Permalink
doc: Fix a bunch of broken links
Browse files Browse the repository at this point in the history
A few categories:

* Links into compiler docs were just all removed as we're not generating
  compiler docs.
* Move up one more level to forcibly go to std docs to fix inlined documentation
  across the facade crates.
  • Loading branch information
alexcrichton committed Mar 8, 2016
1 parent 16fefc5 commit 73db760
Show file tree
Hide file tree
Showing 23 changed files with 135 additions and 139 deletions.
3 changes: 1 addition & 2 deletions src/doc/book/choosing-your-guarantees.md
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,7 @@ borrow checker. Generally we know that such mutations won't happen in a nested f
to check.

For large, complicated programs, it becomes useful to put some things in `RefCell`s to make things
simpler. For example, a lot of the maps in [the `ctxt` struct][ctxt] in the Rust compiler internals
simpler. For example, a lot of the maps in the `ctxt` struct in the Rust compiler internals
are inside this wrapper. These are only modified once (during creation, which is not right after
initialization) or a couple of times in well-separated places. However, since this struct is
pervasively used everywhere, juggling mutable and immutable pointers would be hard (perhaps
Expand Down Expand Up @@ -235,7 +235,6 @@ At runtime each borrow causes a modification/check of the refcount.
[cell-mod]: ../std/cell/
[cell]: ../std/cell/struct.Cell.html
[refcell]: ../std/cell/struct.RefCell.html
[ctxt]: ../rustc/middle/ty/struct.ctxt.html

# Synchronous types

Expand Down
57 changes: 22 additions & 35 deletions src/doc/book/compiler-plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,12 @@ extend the compiler's behavior with new syntax extensions, lint checks, etc.
A plugin is a dynamic library crate with a designated *registrar* function that
registers extensions with `rustc`. Other crates can load these extensions using
the crate attribute `#![plugin(...)]`. See the
[`rustc_plugin`](../rustc_plugin/index.html) documentation for more about the
`rustc_plugin` documentation for more about the
mechanics of defining and loading a plugin.

If present, arguments passed as `#![plugin(foo(... args ...))]` are not
interpreted by rustc itself. They are provided to the plugin through the
`Registry`'s [`args` method](../rustc_plugin/registry/struct.Registry.html#method.args).
`Registry`'s `args` method.

In the vast majority of cases, a plugin should *only* be used through
`#![plugin]` and not through an `extern crate` item. Linking a plugin would
Expand All @@ -30,7 +30,7 @@ of a library.
Plugins can extend Rust's syntax in various ways. One kind of syntax extension
is the procedural macro. These are invoked the same way as [ordinary
macros](macros.html), but the expansion is performed by arbitrary Rust
code that manipulates [syntax trees](../syntax/ast/index.html) at
code that manipulates syntax trees at
compile time.

Let's write a plugin
Expand Down Expand Up @@ -120,19 +120,16 @@ The advantages over a simple `fn(&str) -> u32` are:

In addition to procedural macros, you can define new
[`derive`](../reference.html#derive)-like attributes and other kinds of
extensions. See
[`Registry::register_syntax_extension`](../rustc_plugin/registry/struct.Registry.html#method.register_syntax_extension)
and the [`SyntaxExtension`
enum](https://doc.rust-lang.org/syntax/ext/base/enum.SyntaxExtension.html). For
a more involved macro example, see
extensions. See `Registry::register_syntax_extension` and the `SyntaxExtension`
enum. For a more involved macro example, see
[`regex_macros`](https://github.com/rust-lang/regex/blob/master/regex_macros/src/lib.rs).


## Tips and tricks

Some of the [macro debugging tips](macros.html#debugging-macro-code) are applicable.

You can use [`syntax::parse`](../syntax/parse/index.html) to turn token trees into
You can use `syntax::parse` to turn token trees into
higher-level syntax elements like expressions:

```ignore
Expand All @@ -148,30 +145,21 @@ Looking through [`libsyntax` parser
code](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/parser.rs)
will give you a feel for how the parsing infrastructure works.

Keep the [`Span`s](../syntax/codemap/struct.Span.html) of
everything you parse, for better error reporting. You can wrap
[`Spanned`](../syntax/codemap/struct.Spanned.html) around
your custom data structures.

Calling
[`ExtCtxt::span_fatal`](../syntax/ext/base/struct.ExtCtxt.html#method.span_fatal)
will immediately abort compilation. It's better to instead call
[`ExtCtxt::span_err`](../syntax/ext/base/struct.ExtCtxt.html#method.span_err)
and return
[`DummyResult`](../syntax/ext/base/struct.DummyResult.html),
so that the compiler can continue and find further errors.

To print syntax fragments for debugging, you can use
[`span_note`](../syntax/ext/base/struct.ExtCtxt.html#method.span_note) together
with
[`syntax::print::pprust::*_to_string`](https://doc.rust-lang.org/syntax/print/pprust/index.html#functions).

The example above produced an integer literal using
[`AstBuilder::expr_usize`](../syntax/ext/build/trait.AstBuilder.html#tymethod.expr_usize).
Keep the `Span`s of everything you parse, for better error reporting. You can
wrap `Spanned` around your custom data structures.

Calling `ExtCtxt::span_fatal` will immediately abort compilation. It's better to
instead call `ExtCtxt::span_err` and return `DummyResult` so that the compiler
can continue and find further errors.

To print syntax fragments for debugging, you can use `span_note` together with
`syntax::print::pprust::*_to_string`.

The example above produced an integer literal using `AstBuilder::expr_usize`.
As an alternative to the `AstBuilder` trait, `libsyntax` provides a set of
[quasiquote macros](../syntax/ext/quote/index.html). They are undocumented and
very rough around the edges. However, the implementation may be a good
starting point for an improved quasiquote as an ordinary plugin library.
quasiquote macros. They are undocumented and very rough around the edges.
However, the implementation may be a good starting point for an improved
quasiquote as an ordinary plugin library.


# Lint plugins
Expand Down Expand Up @@ -239,12 +227,11 @@ foo.rs:4 fn lintme() { }

The components of a lint plugin are:

* one or more `declare_lint!` invocations, which define static
[`Lint`](../rustc/lint/struct.Lint.html) structs;
* one or more `declare_lint!` invocations, which define static `Lint` structs;

* a struct holding any state needed by the lint pass (here, none);

* a [`LintPass`](../rustc/lint/trait.LintPass.html)
* a `LintPass`
implementation defining how to check each syntax element. A single
`LintPass` may call `span_lint` for several different `Lint`s, but should
register them all through the `get_lints` method.
Expand Down
2 changes: 1 addition & 1 deletion src/doc/guide-plugins.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
% The (old) Rust Compiler Plugins Guide

This content has moved into
[the Rust Programming Language book](book/plugins.html).
[the Rust Programming Language book](book/compiler-plugins.html).
2 changes: 1 addition & 1 deletion src/doc/style/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ This document is broken into four parts:
cross-cutting topic, starting with
[Ownership and resources](ownership/README.md).

* **[APIs for a changing Rust](changing/README.md)**
* **APIs for a changing Rust**
discusses the forward-compatibility hazards, especially those that interact
with the pre-1.0 library stabilization process.

Expand Down
2 changes: 1 addition & 1 deletion src/doc/style/features/functions-and-methods/input.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ needs to make about its arguments.
On the other hand, generics can make it more difficult to read and understand a
function's signature. Aim for "natural" parameter types that a neither overly
concrete nor overly abstract. See the discussion on
[traits](../../traits/README.md) for more guidance.
[traits](../traits/README.md) for more guidance.


#### Minimizing ownership assumptions:
Expand Down
2 changes: 1 addition & 1 deletion src/doc/style/style/naming/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ The convention for a field `foo: T` is:
here may take `&T` or some other type, depending on the context.)

Note that this convention is about getters/setters on ordinary data types, *not*
on [builder objects](../ownership/builders.html).
on [builder objects](../../ownership/builders.html).

### Escape hatches [FIXME]

Expand Down
4 changes: 2 additions & 2 deletions src/libcollections/btree/set.rs
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,8 @@ use Bound;
/// to any other item, as determined by the [`Ord`] trait, changes while it is in the set. This is
/// normally only possible through [`Cell`], [`RefCell`], global state, I/O, or unsafe code.
///
/// [`BTreeMap`]: ../struct.BTreeMap.html
/// [`Ord`]: ../../core/cmp/trait.Ord.html
/// [`BTreeMap`]: struct.BTreeMap.html
/// [`Ord`]: ../../std/cmp/trait.Ord.html
/// [`Cell`]: ../../std/cell/struct.Cell.html
/// [`RefCell`]: ../../std/cell/struct.RefCell.html
#[derive(Clone, Hash, PartialEq, Eq, Ord, PartialOrd)]
Expand Down
8 changes: 8 additions & 0 deletions src/libcollections/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -71,13 +71,21 @@ extern crate std;
#[cfg(test)]
extern crate test;

#[doc(no_inline)]
pub use binary_heap::BinaryHeap;
#[doc(no_inline)]
pub use btree_map::BTreeMap;
#[doc(no_inline)]
pub use btree_set::BTreeSet;
#[doc(no_inline)]
pub use linked_list::LinkedList;
#[doc(no_inline)]
pub use enum_set::EnumSet;
#[doc(no_inline)]
pub use vec_deque::VecDeque;
#[doc(no_inline)]
pub use string::String;
#[doc(no_inline)]
pub use vec::Vec;

// Needed for the vec! macro
Expand Down
2 changes: 1 addition & 1 deletion src/libcollections/slice.rs
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@
//! * Further methods that return iterators are `.split()`, `.splitn()`,
//! `.chunks()`, `.windows()` and more.
//!
//! *[See also the slice primitive type](../primitive.slice.html).*
//! *[See also the slice primitive type](../../std/primitive.slice.html).*
#![stable(feature = "rust1", since = "1.0.0")]

// Many of the usings in this module are only used in the test configuration.
Expand Down
2 changes: 1 addition & 1 deletion src/libcollections/str.rs
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

//! Unicode string slices.
//!
//! *[See also the `str` primitive type](../primitive.str.html).*
//! *[See also the `str` primitive type](../../std/primitive.str.html).*

#![stable(feature = "rust1", since = "1.0.0")]
Expand Down
54 changes: 27 additions & 27 deletions src/libcollections/string.rs
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ use boxed::Box;
/// contents of the string. It has a close relationship with its borrowed
/// counterpart, the primitive [`str`].
///
/// [`str`]: ../primitive.str.html
/// [`str`]: ../../std/primitive.str.html
///
/// # Examples
///
Expand All @@ -99,7 +99,7 @@ use boxed::Box;
/// hello.push_str("orld!");
/// ```
///
/// [`char`]: ../primitive.char.html
/// [`char`]: ../../std/primitive.char.html
/// [`push()`]: #method.push
/// [`push_str()`]: #method.push_str
///
Expand Down Expand Up @@ -131,7 +131,7 @@ use boxed::Box;
/// println!("The first letter of s is {}", s[0]); // ERROR!!!
/// ```
///
/// [`OsString`]: ../ffi/struct.OsString.html
/// [`OsString`]: ../../std/ffi/struct.OsString.html
///
/// Indexing is intended to be a constant-time operation, but UTF-8 encoding
/// does not allow us to do this. Furtheremore, it's not clear what sort of
Expand All @@ -156,8 +156,8 @@ use boxed::Box;
/// takes_str(&s);
/// ```
///
/// [`&str`]: ../primitive.str.html
/// [`Deref`]: ../ops/trait.Deref.html
/// [`&str`]: ../../std/primitive.str.html
/// [`Deref`]: ../../std/ops/trait.Deref.html
///
/// This will create a [`&str`] from the `String` and pass it in. This
/// conversion is very inexpensive, and so generally, functions will accept
Expand Down Expand Up @@ -280,10 +280,10 @@ pub struct String {
/// an analogue to `FromUtf8Error`, and you can get one from a `FromUtf8Error`
/// through the [`utf8_error()`] method.
///
/// [`Utf8Error`]: ../str/struct.Utf8Error.html
/// [`std::str`]: ../str/index.html
/// [`u8`]: ../primitive.u8.html
/// [`&str`]: ../primitive.str.html
/// [`Utf8Error`]: ../../std/str/struct.Utf8Error.html
/// [`std::str`]: ../../std/str/index.html
/// [`u8`]: ../../std/primitive.u8.html
/// [`&str`]: ../../std/primitive.str.html
/// [`utf8_error()`]: #method.utf8_error
///
/// # Examples
Expand Down Expand Up @@ -414,9 +414,9 @@ impl String {
/// requires that it is valid UTF-8. `from_utf8()` checks to ensure that
/// the bytes are valid UTF-8, and then does the conversion.
///
/// [`&str`]: ../primitive.str.html
/// [`u8`]: ../primitive.u8.html
/// [`Vec<u8>`]: ../vec/struct.Vec.html
/// [`&str`]: ../../std/primitive.str.html
/// [`u8`]: ../../std/primitive.u8.html
/// [`Vec<u8>`]: ../../std/vec/struct.Vec.html
///
/// If you are sure that the byte slice is valid UTF-8, and you don't want
/// to incur the overhead of the validity check, there is an unsafe version
Expand All @@ -431,7 +431,7 @@ impl String {
/// If you need a `&str` instead of a `String`, consider
/// [`str::from_utf8()`].
///
/// [`str::from_utf8()`]: ../str/fn.from_utf8.html
/// [`str::from_utf8()`]: ../../std/str/fn.from_utf8.html
///
/// # Errors
///
Expand Down Expand Up @@ -488,8 +488,8 @@ impl String {
/// `from_utf8_lossy()` will replace any invalid UTF-8 sequences with
/// `U+FFFD REPLACEMENT CHARACTER`, which looks like this: �
///
/// [`u8`]: ../primitive.u8.html
/// [byteslice]: ../primitive.slice.html
/// [`u8`]: ../../std/primitive.u8.html
/// [byteslice]: ../../std/primitive.slice.html
///
/// If you are sure that the byte slice is valid UTF-8, and you don't want
/// to incur the overhead of the conversion, there is an unsafe version
Expand All @@ -504,7 +504,7 @@ impl String {
/// it's already valid UTF-8, we don't need a new allocation. This return
/// type allows us to handle both cases.
///
/// [`Cow<'a, str>`]: ../borrow/enum.Cow.html
/// [`Cow<'a, str>`]: ../../std/borrow/enum.Cow.html
///
/// # Examples
///
Expand Down Expand Up @@ -1014,7 +1014,7 @@ impl String {
/// Panics if `new_len` > current length, or if `new_len` does not lie on a
/// [`char`] boundary.
///
/// [`char`]: ../primitive.char.html
/// [`char`]: ../../std/primitive.char.html
///
/// # Examples
///
Expand Down Expand Up @@ -1076,7 +1076,7 @@ impl String {
/// Panics if `idx` is larger than or equal to the `String`'s length,
/// or if it does not lie on a [`char`] boundary.
///
/// [`char`]: ../primitive.char.html
/// [`char`]: ../../std/primitive.char.html
///
/// # Examples
///
Expand Down Expand Up @@ -1116,7 +1116,7 @@ impl String {
/// Panics if `idx` is larger than the `String`'s length, or if it does not
/// lie on a [`char`] boundary.
///
/// [`char`]: ../primitive.char.html
/// [`char`]: ../../std/primitive.char.html
///
/// # Examples
///
Expand Down Expand Up @@ -1255,7 +1255,7 @@ impl String {
/// Panics if the starting point or end point do not lie on a [`char`]
/// boundary, or if they're out of bounds.
///
/// [`char`]: ../primitive.char.html
/// [`char`]: ../../std/primitive.char.html
///
/// # Examples
///
Expand Down Expand Up @@ -1353,10 +1353,10 @@ impl FromUtf8Error {
/// an analogue to `FromUtf8Error`. See its documentation for more details
/// on using it.
///
/// [`Utf8Error`]: ../str/struct.Utf8Error.html
/// [`std::str`]: ../str/index.html
/// [`u8`]: ../primitive.u8.html
/// [`&str`]: ../primitive.str.html
/// [`Utf8Error`]: ../../std/str/struct.Utf8Error.html
/// [`std::str`]: ../../std/str/index.html
/// [`u8`]: ../../std/primitive.u8.html
/// [`&str`]: ../../std/primitive.str.html
///
/// # Examples
///
Expand Down Expand Up @@ -1695,9 +1695,9 @@ impl ops::DerefMut for String {
/// [`String`] without error, this type will never actually be returned. As
/// such, it is only here to satisfy said signature, and is useless otherwise.
///
/// [`FromStr`]: ../str/trait.FromStr.html
/// [`FromStr`]: ../../std/str/trait.FromStr.html
/// [`String`]: struct.String.html
/// [`from_str()`]: ../str/trait.FromStr.html#tymethod.from_str
/// [`from_str()`]: ../../std/str/trait.FromStr.html#tymethod.from_str
#[stable(feature = "str_parse_error", since = "1.5.0")]
#[derive(Copy)]
pub enum ParseError {}
Expand Down Expand Up @@ -1749,7 +1749,7 @@ impl Eq for ParseError {}
/// [`Display`] should be implemented instead, and you get the `ToString`
/// implementation for free.
///
/// [`Display`]: ../fmt/trait.Display.html
/// [`Display`]: ../../std/fmt/trait.Display.html
#[stable(feature = "rust1", since = "1.0.0")]
pub trait ToString {
/// Converts the given value to a `String`.
Expand Down
2 changes: 1 addition & 1 deletion src/libcore/any.rs
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
//! Note that &Any is limited to testing whether a value is of a specified
//! concrete type, and cannot be used to test whether a type implements a trait.
//!
//! [`Box`]: ../boxed/struct.Box.html
//! [`Box`]: ../../std/boxed/struct.Box.html
//!
//! # Examples
//!
Expand Down
Loading

0 comments on commit 73db760

Please sign in to comment.