Update docs for rustc_lint crateification.

src/librustc/lint/builtin.rs

@@ -8,22 +8,11 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Lints built in to rustc.
+//! Some lints that are built in to the compiler.
 //!
-//! This is a sibling of `lint::context` in order to ensure that
-//! lints implemented here use the same public API as lint plugins.
-//!
-//! To add a new lint to rustc, declare it here using `declare_lint!()`.
-//! Then add code to emit the new lint in the appropriate circumstances.
-//! You can do that in an existing `LintPass` if it makes sense, or in
-//! a new `LintPass`, or using `Session::add_lint` elsewhere in the
-//! compiler. Only do the latter if the check can't be written cleanly
-//! as a `LintPass`.
-//!
-//! If you define a new `LintPass`, you will also need to add it to the
-//! `add_builtin!` or `add_builtin_with_new!` invocation in `context.rs`.
-//! Use the former for unit-like structs and the latter for structs with
-//! a `pub fn new()`.
+//! These are the built-in lints that are emitted direct in the main
+//! compiler code, rather than using their own custom pass. Those
+//! lints are all available in `rustc_lint::builtin`.
 
 use lint::{LintPass, LintArray};
 

src/librustc_lint/builtin.rs

@@ -8,20 +8,23 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Lints built in to rustc.
+//! Lints in the Rust compiler.
 //!
-//! This is a sibling of `lint::context` in order to ensure that
-//! lints implemented here use the same public API as lint plugins.
+//! This contains lints which can feasibly be implemented as their own
+//! AST visitor. Also see `rustc::lint::builtin`, which contains the
+//! definitions of lints that are emitted directly inside the main
+//! compiler.
 //!
 //! To add a new lint to rustc, declare it here using `declare_lint!()`.
 //! Then add code to emit the new lint in the appropriate circumstances.
-//! You can do that in an existing `LintPass` if it makes sense, or in
-//! a new `LintPass`, or using `Session::add_lint` elsewhere in the
-//! compiler. Only do the latter if the check can't be written cleanly
-//! as a `LintPass`.
+//! You can do that in an existing `LintPass` if it makes sense, or in a
+//! new `LintPass`, or using `Session::add_lint` elsewhere in the
+//! compiler. Only do the latter if the check can't be written cleanly as a
+//! `LintPass` (also, note that such lints will need to be defined in
+//! `rustc::lint::builtin`, not here).
 //!
 //! If you define a new `LintPass`, you will also need to add it to the
-//! `add_builtin!` or `add_builtin_with_new!` invocation in `context.rs`.
+//! `add_builtin!` or `add_builtin_with_new!` invocation in `lib.rs`.
 //! Use the former for unit-like structs and the latter for structs with
 //! a `pub fn new()`.
 

src/librustc_lint/lib.rs

@@ -8,7 +8,12 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Many of the lints built into the Rust compiler.
+//! Lints in the Rust compiler.
+//!
+//! This currently only contains the definitions and implementations
+//! of most of the lints that `rustc` supports directly, it does not
+//! contain the infrastructure for defining/registering lints. That is
+//! available in `rustc::lint` and `rustc::plugin` respectively.
 //!
 //! # Note
 //!
@@ -54,6 +59,9 @@ use lint::{LintPassObject, LintId};
 
 mod builtin;
 
+/// Tell the `LintStore` about all the built-in lints (the ones
+/// defined in this crate and the ones defined in
+/// `rustc::lint::builtin`).
 pub fn register_builtins(store: &mut lint::LintStore, sess: Option<&Session>) {
     macro_rules! add_builtin {
         ($sess:ident, $($name:ident),*,) => (