Document declare_clippy_lint macro

Split up from my work on updating CONTRIBUTING.md, which is slowly
making progress.

cc #2666

Author: phansch

clippy_lints/src/lib.rs

@@ -37,8 +37,53 @@ extern crate syntax_pos;
 
 use toml;
 
-// Currently, categories "style", "correctness", "complexity" and "perf" are enabled by default,
-// as said in the README.md of this repository. If this changes, please update README.md.
+/// Macro used to declare a Clippy lint.
+///
+/// Every lint declaration consists of 4 parts:
+///
+/// 1. The documentation above the lint, which is used for the website
+/// 2. The `LINT_NAME`. See [lint naming][lint_naming] on lint naming conventions.
+/// 3. The `lint_level`, which is a mapping from *one* of our lint groups to `Allow`, `Warn` or
+///    `Deny`. The lint level here has nothing to do with what lint groups the lint is a part of.
+/// 4. The `description` that contains a short explanation on what's wrong with code where the
+///    lint is triggered.
+///
+/// Currently the categories `style`, `correctness`, `complexity` and `perf` are enabled by default.
+/// As said in the README.md of this repository, if the lint level mapping changes, please update
+/// README.md.
+///
+/// # Example
+///
+/// ```
+/// # #![feature(rustc_private)]
+/// # #[allow(unused_extern_crates)]
+/// # extern crate rustc;
+/// # #[macro_use]
+/// # use clippy_lints::declare_clippy_lint;
+/// use rustc::declare_tool_lint;
+///
+/// /// **What it does:** Checks for ... (describe what the lint matches).
+/// ///
+/// /// **Why is this bad?** Supply the reason for linting the code.
+/// ///
+/// /// **Known problems:** None. (Or describe where it could go wrong.)
+/// ///
+/// /// **Example:**
+/// ///
+/// /// ```rust
+/// /// // Bad
+/// /// Insert a short example of code that triggers the lint
+/// ///
+/// /// // Good
+/// /// Insert a short example of improved code that doesn't trigger the lint
+/// /// ```
+/// declare_clippy_lint! {
+///     pub LINT_NAME,
+///     pedantic,
+///     "description"
+/// }
+/// ```
+/// [lint_naming]: https://rust-lang.github.io/rfcs/0344-conventions-galore.html#lints
 #[macro_export]
 macro_rules! declare_clippy_lint {
     { pub $name:tt, style, $description:tt } => {