Add module documentation.

src/api/compile.rs

@@ -2,6 +2,7 @@
 
 use crate::parser::{ParseResult, ParseState};
 use crate::{Engine, OptimizationLevel, Scope, AST};
+use std::mem;
 #[cfg(feature = "no_std")]
 use std::prelude::v1::*;
 
@@ -222,7 +223,12 @@ impl Engine {
             self.token_mapper.as_ref().map(<_>::as_ref),
         );
         let mut state = ParseState::new(self, scope, tokenizer_control);
-        self.parse(&mut stream.peekable(), &mut state, optimization_level)
+        let mut ast = self.parse(&mut stream.peekable(), &mut state, optimization_level)?;
+        #[cfg(feature = "metadata")]
+        ast.set_doc(mem::take(
+            &mut state.tokenizer_control.borrow_mut().global_comments,
+        ));
+        Ok(ast)
     }
     /// Compile a string containing an expression into an [`AST`],
     /// which can be used later for evaluation.

src/api/optimize.rs

@@ -2,6 +2,7 @@
 #![cfg(not(feature = "no_optimize"))]
 
 use crate::{Engine, OptimizationLevel, Scope, AST};
+use std::mem;
 
 impl Engine {
     /// Control whether and how the [`Engine`] will optimize an [`AST`] after compilation.
@@ -59,13 +60,18 @@ impl Engine {
             .map(|f| f.func.get_script_fn_def().unwrap().clone())
             .collect();
 
-        crate::optimizer::optimize_into_ast(
+        let mut new_ast = crate::optimizer::optimize_into_ast(
             self,
             scope,
             ast.take_statements(),
             #[cfg(not(feature = "no_function"))]
             lib,
             optimization_level,
-        )
+        );
+
+        #[cfg(feature = "metadata")]
+        new_ast.set_doc(mem::take(ast.doc_mut()));
+
+        new_ast
     }
 }

src/api/run.rs

@@ -25,9 +25,7 @@ impl Engine {
         let (stream, tokenizer_control) =
             self.lex_raw(&scripts, self.token_mapper.as_ref().map(<_>::as_ref));
         let mut state = ParseState::new(self, scope, tokenizer_control);
-
         let ast = self.parse(&mut stream.peekable(), &mut state, self.optimization_level)?;
-
         self.run_ast_with_scope(scope, &ast)
     }
     /// Evaluate an [`AST`], returning any error (if any).