Better tips for Interpreter & InterpreterConfig (RustPython#5047)

Co-authored-by: fanninpm <[email protected]>

Author: youknowone

src/interpreter.rs

@@ -2,6 +2,40 @@ use rustpython_vm::{Interpreter, Settings, VirtualMachine};
 
 pub type InitHook = Box<dyn FnOnce(&mut VirtualMachine)>;
 
+/// The convenient way to create [rustpython_vm::Interpreter] with stdlib and other stuffs.
+///
+/// Basic usage:
+/// ```
+/// let interpreter = rustpython::InterpreterConfig::new()
+///     .init_stdlib()
+///     .interpreter();
+/// ```
+///
+/// To override [rustpython_vm::Settings]:
+/// ```
+/// use rustpython_vm::Settings;
+/// // Override your settings here.
+/// let mut settings = Settings::default();
+/// settings.debug = true;
+/// // You may want to add paths to `rustpython_vm::Settings::path_list` to allow import python libraries.
+/// settings.path_list.push("".to_owned());  // add current working directory
+/// let interpreter = rustpython::InterpreterConfig::new()
+///     .settings(settings)
+///     .interpreter();
+/// ```
+///
+/// To add native modules:
+/// ```compile_fail
+/// let interpreter = rustpython::InterpreterConfig::new()
+///     .init_stdlib()
+///     .init_hook(Box::new(|vm| {
+///         vm.add_native_module(
+///             "your_module_name".to_owned(),
+///             Box::new(your_module::make_module),
+///         );
+///     }))
+///     .interpreter();
+/// ```
 #[derive(Default)]
 pub struct InterpreterConfig {
     settings: Option<Settings>,

vm/src/vm/interpreter.rs

@@ -28,7 +28,10 @@ pub struct Interpreter {
 }
 
 impl Interpreter {
-    /// To create with stdlib, use `with_init`
+    /// This is a bare unit to build up an interpreter without the standard library.
+    /// To create an interpreter with the standard library with the `rustpython` crate, use `rustpython::InterpreterConfig`.
+    /// To create an interpreter without the `rustpython` crate, but only with `rustpython-vm`,
+    /// try to build one from the source code of `InterpreterConfig`. It will not be a one-liner but it also will not be too hard.
     pub fn without_stdlib(settings: Settings) -> Self {
         Self::with_init(settings, |_| {})
     }