diff --git a/doc/src/rust/packages/create.md b/doc/src/rust/packages/create.md
index c4ee27e4..53ac17a0 100644
--- a/doc/src/rust/packages/create.md
+++ b/doc/src/rust/packages/create.md
@@ -66,6 +66,9 @@ In fact, this exactly is how Rhai's built-in packages, such as `BasicMathPackage
 `rhai::plugins::combine_with_exported_module!` adds all functions and constants from the
 [plugins][plugin module] definition into the package itself.
 
+All sub-modules are _flattened_ (i.e. all functions and constants defined within sub-modules are registered
+at the top level) and so there will not be any sub-modules added to the package.
+
 ```rust
 // Import necessary types and traits.
 use rhai::{
@@ -104,8 +107,17 @@ def_package!(rhai:MyPackage:"My own personal super package", module, {
 
     // Merge all registered functions and constants from the plugin module into the custom package.
     //
+    // Functions in the sub-module 'my_sub_module' are flattened and registered at the top level
+    // instead of in a sub-module.
+    //
     // The text string name in the middle parameter can be anything and is reserved for future use;
     // it is recommended to be an ID string that uniquely identifies the module.
+    //
+    // This call ends up registering three functions at the top level of the package:
+    //   1) greet
+    //   2) get_num
+    //   3) get_sub_num (flattened from sub-module 'my_sub_module')
+    //
     combine_with_exported_module!(module, "my-functions", my_module));
 });
 ```