From fcc363af60fe3e16f205a68ba2d582cfd3fb6cf1 Mon Sep 17 00:00:00 2001
From: Stephen Chung <schungx@live.com>
Date: Thu, 1 Dec 2022 23:29:42 +0800
Subject: [PATCH] Add doc-comments on plugin modules to Module::doc field.

---
 CHANGELOG.md               |  1 +
 codegen/Cargo.toml         |  4 ++--
 codegen/src/module.rs      |  7 +++++++
 codegen/src/rhai_module.rs | 13 +++++++++++++
 codegen/src/test/module.rs | 13 +++++++++++++
 5 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f4fb854f..0318804f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -44,6 +44,7 @@ Enhancements
 * `Engine::set_XXX` API can now be chained.
 * `EvalContext::scope_mut` now returns `&mut Scope` instead of `&mut &mut Scope`.
 * Line-style doc-comments are now merged into a single string to avoid creating many strings. Block-style doc-comments continue to be independent strings.
+* Doc-comments on plugin modules are now captured in the module's `doc` field.
 
 
 Version 1.11.0
diff --git a/codegen/Cargo.toml b/codegen/Cargo.toml
index 99583472..6364db5c 100644
--- a/codegen/Cargo.toml
+++ b/codegen/Cargo.toml
@@ -1,11 +1,11 @@
 [package]
 name = "rhai_codegen"
-version = "1.4.3"
+version = "1.4.4"
 edition = "2018"
 resolver = "2"
 authors = ["jhwgh1968", "Stephen Chung"]
 description = "Procedural macros support package for Rhai, a scripting language and engine for Rust"
-keywords = ["rhai", "scripting", "scripting-engine", "scripting-language", "embedded", "plugin", "macros", "code-generation"]
+keywords = ["scripting", "scripting-engine", "scripting-language", "embedded", "plugin"]
 categories = ["no-std", "embedded", "wasm", "parser-implementations"]
 homepage = "https://rhai.rs/book/plugins/index.html"
 repository = "https://github.com/rhaiscript/rhai"
diff --git a/codegen/src/module.rs b/codegen/src/module.rs
index 9206be78..ea577f5f 100644
--- a/codegen/src/module.rs
+++ b/codegen/src/module.rs
@@ -106,6 +106,7 @@ impl Module {
 impl Parse for Module {
     fn parse(input: ParseStream) -> syn::Result<Self> {
         let mut mod_all: syn::ItemMod = input.parse()?;
+
         let fns: Vec<_>;
         let mut consts = Vec::new();
         let mut custom_types = Vec::new();
@@ -269,11 +270,17 @@ impl Module {
         let (.., orig_content) = mod_all.content.take().unwrap();
         let mod_attrs = mem::take(&mut mod_all.attrs);
 
+        #[cfg(feature = "metadata")]
+        let mod_doc = crate::attrs::doc_attributes(&mod_attrs)?.join("\n");
+        #[cfg(not(feature = "metadata"))]
+        let mod_doc = String::new();
+
         if !params.skip {
             // Generate new module items.
             //
             // This is done before inner module recursive generation, because that is destructive.
             let mod_gen = crate::rhai_module::generate_body(
+                &mod_doc,
                 &mut fns,
                 &consts,
                 &custom_types,
diff --git a/codegen/src/rhai_module.rs b/codegen/src/rhai_module.rs
index bedccdd5..42b18d2b 100644
--- a/codegen/src/rhai_module.rs
+++ b/codegen/src/rhai_module.rs
@@ -26,6 +26,7 @@ pub struct ExportedType {
 }
 
 pub fn generate_body(
+    doc: &str,
     fns: &mut [ExportedFn],
     consts: &[ExportedConst],
     custom_types: &[ExportedType],
@@ -246,6 +247,17 @@ pub fn generate_body(
         gen_fn_tokens.push(function.generate_impl(&fn_token_name.to_string()));
     }
 
+    let module_docs = if doc.is_empty() {
+        None
+    } else {
+        Some(
+            syn::parse2::<syn::Stmt>(quote! {
+                m.set_doc(#doc);
+            })
+            .unwrap(),
+        )
+    };
+
     let mut generate_fn_call = syn::parse2::<syn::ItemMod>(quote! {
         pub mod generate_info {
             #[allow(unused_imports)]
@@ -254,6 +266,7 @@ pub fn generate_body(
             #[doc(hidden)]
             pub fn rhai_module_generate() -> Module {
                 let mut m = Module::new();
+                #module_docs
                 rhai_generate_into_module(&mut m, false);
                 m.build_index();
                 m
diff --git a/codegen/src/test/module.rs b/codegen/src/test/module.rs
index abbdd3ab..3575d2c4 100644
--- a/codegen/src/test/module.rs
+++ b/codegen/src/test/module.rs
@@ -403,6 +403,12 @@ mod generate_tests {
     #[test]
     fn one_factory_fn_with_comments_module() {
         let input_tokens: TokenStream = quote! {
+            /// This is the one_fn module!
+            /** block doc-comment
+             *  multi-line
+             */
+            /// Another line!
+            /// Final line!
             pub mod one_fn {
                 /// This is a doc-comment.
                 /// Another line.
@@ -419,6 +425,12 @@ mod generate_tests {
         };
 
         let expected_tokens = quote! {
+            /// This is the one_fn module!
+            /** block doc-comment
+             *  multi-line
+             */
+            /// Another line!
+            /// Final line!
             pub mod one_fn {
                 /// This is a doc-comment.
                 /// Another line.
@@ -437,6 +449,7 @@ mod generate_tests {
                 #[doc(hidden)]
                 pub fn rhai_module_generate() -> Module {
                     let mut m = Module::new();
+                    m.set_doc("/// This is the one_fn module!\n/** block doc-comment\n             *  multi-line\n             */\n/// Another line!\n/// Final line!");
                     rhai_generate_into_module(&mut m, false);
                     m.build_index();
                     m