Module system improvement

content/docs/guide/modules.mdx

@@ -4,14 +4,17 @@ description: Module declarations, imports, re-exports, and module resolution rul
 icon: FolderTree
 ---
 
+Mist's module system was created to fix Rust's dreaded parent-declared module system, files declare themselves and their publicity via `pub module my_mod;` as the first statement.
+
+
 ```mist
-// Declare a submodule
+// Declare a module
 pub module foo;
 
 // Import
 use std::collections::HashMap;
 
-// Re-exporting import
+// Re-exporting import (alias)
 pub use my_module::MyType;
 ```
 
@@ -23,7 +26,8 @@ Mist maps the module tree to Rust's module system:
 |------------------------------|------------------------------|
 | `src/main.mist`              | `.mist/src/main.rs`          |
 | `src/utils/package.mist`     | `.mist/src/utils/mod.rs`     |
-| `src/foo.mist`               | `.mist/src/foo.rs`           |
+| `pub module foo;`            | `.mist/src/foo.rs`           |
-| `src/utils/helper.mist`      | `.mist/src/utils/helper.rs`  |
 
-A `package.mist` file acts as a directory's module root, analogous to `mod.rs`.
+A `package.mist` file acts as a directory's module root, analogous to `mod.rs`, but it's not required, as long as the directory contains `.mist` files, it will auto generate `mod.rs`.
+
+#### *💡 Tip*: File names don't matter, `module my_mod` determines the name.