From d7292fe235bc9d72c9c528e2c2bfc5d07ad7baa2 Mon Sep 17 00:00:00 2001
From: llogiq <bogusandre@gmail.com>
Date: Mon, 14 Dec 2015 08:03:01 +0100
Subject: [PATCH] more docs

---
 src/mutex_atomic.rs | 14 ++++++++++++++
 src/transmute.rs    |  7 +++++++
 2 files changed, 21 insertions(+)

diff --git a/src/mutex_atomic.rs b/src/mutex_atomic.rs
index e6d1fc8a888a..40f7d21f43c8 100644
--- a/src/mutex_atomic.rs
+++ b/src/mutex_atomic.rs
@@ -11,12 +11,26 @@ use rustc::middle::subst::ParamSpace;
 
 use utils::{span_lint, MUTEX_PATH, match_type};
 
+/// **What it does:** It `Warn`s on usages of `Mutex<X>` where an atomic will do
+///
+/// **Why is this bad?** Using a Mutex just to make access to a plain bool or reference sequential is shooting flies with cannons. `std::atomic::AtomicBool` and `std::atomic::AtomicPtr` are leaner and faster.
+///
+/// **Known problems:** This lint cannot detect if the Mutex is actually used for waiting before a critical section.
+///
+/// **Example:** `let x = Mutex::new(&y);`
 declare_lint! {
     pub MUTEX_ATOMIC,
     Warn,
     "using a Mutex where an atomic value could be used instead"
 }
 
+/// **What it does:** It `Warn`s on usages of `Mutex<X>` where `X` is an integral type.
+///
+/// **Why is this bad?** Using a Mutex just to make access to a plain integer sequential is shooting flies with cannons. `std::atomic::usize` is leaner and faster.
+///
+/// **Known problems:** This lint cannot detect if the Mutex is actually used for waiting before a critical section.
+///
+/// **Example:** `let x = Mutex::new(0usize);`
 declare_lint! {
     pub MUTEX_INTEGER,
     Allow,
diff --git a/src/transmute.rs b/src/transmute.rs
index ab1397ea7fe4..c71468bf5a08 100644
--- a/src/transmute.rs
+++ b/src/transmute.rs
@@ -2,6 +2,13 @@ use rustc::lint::*;
 use rustc_front::hir::*;
 use utils;
 
+/// **What it does:** This lint checks for transmutes to the original type of the object. It is `Warn` by default.
+///
+/// **Why is this bad?** Readability. The code tricks people into thinking that the original value was of some other type.
+///
+/// **Known problems:** None.
+///
+/// **Example:** `core::intrinsics::transmute(t)` where the result type is the same as `t`'s.
 declare_lint! {
     pub USELESS_TRANSMUTE,
     Warn,