From fb53ec9b6915760013865e62772f3404b3563e08 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Sun, 21 Jul 2019 13:04:59 -0700
Subject: [PATCH] Attempt to clarify "no more mod.rs".

The example code was a little confusing. Instead, use a table which compares
the directory structure.

Not sure if this is clear enough, it's a little awkward to explain.
---
 src/rust-2018/module-system/path-clarity.md | 52 ++++++++++++++-------
 1 file changed, 35 insertions(+), 17 deletions(-)

diff --git a/src/rust-2018/module-system/path-clarity.md b/src/rust-2018/module-system/path-clarity.md
index e4522c78..19bbf739 100644
--- a/src/rust-2018/module-system/path-clarity.md
+++ b/src/rust-2018/module-system/path-clarity.md
@@ -169,10 +169,8 @@ mod submodule {
 In Rust 2015, if you have a submodule:
 
 ```rust,ignore
-///  foo.rs
-///  or
-///  foo/mod.rs
-
+// This `mod` declaration looks for the `foo` module in
+// `foo.rs` or `foo/mod.rs`.
 mod foo;
 ```
 
@@ -180,23 +178,43 @@ It can live in `foo.rs` or `foo/mod.rs`. If it has submodules of its own, it
 *must* be `foo/mod.rs`. So a `bar` submodule of `foo` would live at
 `foo/bar.rs`.
 
-In Rust 2018, `mod.rs` is no longer needed.
-
-```rust,ignore
-///  foo.rs
-///  foo/bar.rs
-
-mod foo;
-
-/// in foo.rs
-mod bar;
-```
-
-`foo.rs` can just be `foo.rs`,
+In Rust 2018 the restriction that a module with submodules must be named
+`mod.rs` is lifted. `foo.rs` can just be `foo.rs`,
 and the submodule is still `foo/bar.rs`. This eliminates the special
 name, and if you have a bunch of files open in your editor, you can clearly
 see their names, instead of having a bunch of tabs named `mod.rs`.
 
+<table>
+  <thead>
+    <tr>
+      <th>Rust 2015</th>
+      <th>Rust 2018</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+<pre>
+.
+├── lib.rs
+└── foo/
+    ├── mod.rs
+    └── bar.rs
+</pre>
+    </td>
+    <td>
+<pre>
+.
+├── lib.rs
+├── foo.rs
+└── foo/
+    └── bar.rs
+</pre>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
 ### `use` paths
 
 ![Minimum Rust version: 1.32](https://img.shields.io/badge/Minimum%20Rust%20Version-1.32-brightgreen.svg)