modules: add explanatory commentary to solution

src/modules/solution.md

@@ -186,3 +186,26 @@ fn main() {
     window.draw();
 }
 ```
+
+The solution demonstrates the standard Rust module hierarchy and visibility
+rules:
+
+- **Module Hierarchy:** Sub-modules are placed in a directory (`src/widgets/`)
+  and declared in a corresponding file (`src/widgets.rs`).
+- **Encapsulation:** Visibility is controlled with `pub`. Fields remain private
+  by default, while types and the `Widget` trait are exposed for external use.
+- **Re-exports:** Using `pub use` in `src/widgets.rs` provides a flat public
+  API, allowing users to import `widgets::Button` instead of the internal
+  `widgets::button::Button`.
+- **Path Resolution:** Sub-modules use `super::Widget` to refer to items in the
+  parent module.
+
+<details>
+
+- **Module Styles:** This structure uses the modern (Rust 2018+) module style.
+  Previously, `src/widgets/mod.rs` was required instead of `src/widgets.rs`.
+- **API Design:** Re-exporting is a powerful tool for decoupling your internal
+  code organization from your library's public interface, allowing for
+  refactoring without breaking changes.
+
+</details>