address nits and improve docs

clippy_lints/src/module_inception.rs

@@ -4,7 +4,10 @@ use utils::span_lint;
 
 /// **What it does:** Checks for modules that have the same name as their parent module
 ///
-/// **Why is this bad?** A typical beginner mistake is to have `mod foo;` and again `mod foo { .. }` in `foo.rs`
+/// **Why is this bad?** A typical beginner mistake is to have `mod foo;` and again `mod foo { .. }` in `foo.rs`.
+///                      The expectation is that items inside the inner `mod foo { .. }` are then available
+///                      through `foo::x`, but they are only available through `foo::foo::x`.
+///                      If this is done on purpose, it would be better to choose a more representative module name.
 ///
 /// **Known problems:** None.
 ///

tests/compile-fail/module_inception.rs

@@ -5,11 +5,12 @@
 mod foo {
     mod bar {
         mod bar { //~ ERROR module has the same name as its containing module
-
+            mod foo {}
         }
+        mod foo {}
     }
     mod foo { //~ ERROR module has the same name as its containing module
-
+        mod bar {}
     }
 }