Updates per chatgpt review

Author: frank-at-adacore

courses/rust_essentials/180_modules/02-filesystem_hierarchy.rst

@@ -37,12 +37,11 @@ Mapping Modules to Files
 * Rust looks for
 
   * :filename:`cleaner.rs`
-
-    * Preferred modern style
-
   * :filename:`cleaner/mod.rs`
 
-    * Older style
+.. note::
+
+  :filename:`cleaner/mod.rs` is legacy style but still common
 
 -------------------------
 Directory-based Modules

courses/rust_essentials/180_modules/03-visibility.rst

@@ -17,6 +17,10 @@ Private by Default
   * Child module can see everything in its parent
   * Parent can only see :rust:`pub` items in its child
 
+----------------------
+Private Code Example
+----------------------
+
 .. code:: rust
 
   mod outer {
@@ -37,6 +41,10 @@ Private by Default
 
 :error:`error[E0603]: function 'private' is private`
 
+.. note::
+
+  Compiler prevents illegal usage
+
 ----------------------------
 Struct and Enum Visibility
 ----------------------------

courses/rust_essentials/180_modules/04-encapsulation.rst

@@ -6,34 +6,25 @@ Encapsulation
 Why Encapsulate?
 ------------------
 
-* Invariants - protect internal state of a data structure
+* Protect internal state of a data structure
 
-  * Ensure data is always valid
-
-    * Can only be changed via approved logic
+  * Ensure data is always valid via getter/setter API's
 
 * Decoupling - hiding implementation details
 
-  * Can change your internal code without breaking client
+  * Change your code without breaking client
 
     * E.g., swapping an array for a :rust:`Vec`
 
-* API Surface - smaller public API
-
-  * Easier to document
-  * Easier to learn
-  * Harder to misuse
-
 --------------------------
 Encapsulation in Structs
 --------------------------
 
 * *Gatekeeper* pattern
 
-  * Keep fields private (default behavior)
-  * Provide a :rust:`pub fn new(...)` constructor
+  * Keep fields private
 
-    * Ensure struct starts in valid state
+    * Only your code can modify fields
 
   * Provide :rust:`pub` getter and setter methods
 
@@ -76,6 +67,6 @@ Breaking Encapsulation
 
 .. note::
 
-  Encapsulation is not just "hiding" code; it is about **guaranteeing correctness**
+  Encapsulation hides code to help guarantee correctness
 
-  If a field is private, you guarantee no outside code can put an "illegal" value in
+  Private fields cannot have "illegal" values

courses/rust_essentials/180_modules/05-use_super_self.rst

@@ -2,6 +2,35 @@
 "use", "super", "self"
 ========================
 
+-------------------------
+Dealing with Long Paths
+-------------------------
+
+.. code:: rust
+
+  mod greenhouse {
+      pub mod shelf {
+          pub mod cactus {
+              pub fn water_cactus() {
+                  println!("Watering the cactus");
+              }
+              pub fn touch_spine() {
+                  println!("Touching the prickly thing");
+              }
+          }
+      }
+  }
+
+  fn main() {
+      // This is repetitive and hard to read
+      greenhouse::shelf::cactus::water_cactus();
+      greenhouse::shelf::cactus::touch_spine();
+      greenhouse::shelf::cactus::water_cactus();
+      greenhouse::shelf::cactus::touch_spine();
+  }
+
+*Wouldn't it be nice to shorten these paths?*
+
 --------------------
 The "use" Shortcut
 --------------------
@@ -14,17 +43,34 @@ The "use" Shortcut
 
   * As if it was in your own module
 
-* Use the wildcard "*" to get everything
-
-  * :rust:`use std::io::*;` gets all items from :rust:`std::io`
-  * But it makes name clashes more likely
 
 * Simplify (and reduce clashes) with *renaming*
 
   .. code:: rust
 
     use std::io::Result as IoResult;
 
+-----------------------
+"use" with a Wildcard
+-----------------------
+
+* Use the wildcard "*" (:dfn:`glob import`) to get everything
+
+* When to use it
+
+  * Common in :rust:`mod tests` to test private items easily
+  * Used in preludes to load essential traits
+  * Speeds up prototyping
+
+* When to avoid it
+
+  * Makes it hard to find things for coder and autocomplete
+  * Globbed modules use the same name causes compilation errors
+
+.. note:: 
+
+  Use **nested imports** - :rust:`use std::io::(self, Read, Write);`
+
 ----------------
 Relative Paths
 ----------------