Fix module level documentation

crates/rune-modules/src/http.rs

@@ -52,9 +52,18 @@ use rune::{Any, Module, Value, ContextError};
 use rune::runtime::{Bytes, Ref, Formatter, VmResult};
 use rune::alloc::fmt::TryWrite;
 
-/// Construct the `http` module.
+/// A simple HTTP module for Rune.
+///
+/// # Examples
+///
+/// ```rune,no_run
+/// let res = http::get("https://httpstat.us/200?sleep=100").await;
+///
+/// dbg!(res.text().await?);
+/// ```
+#[rune::module(::http)]
 pub fn module(_stdio: bool) -> Result<Module, ContextError> {
-    let mut module = Module::with_crate("http")?;
+    let mut module = Module::from_meta(self::module_meta)?;
 
     module.ty::<Client>()?;
     module.ty::<Response>()?;
@@ -81,6 +90,7 @@ pub fn module(_stdio: bool) -> Result<Module, ContextError> {
     Ok(module)
 }
 
+/// An error returned by methods in the `http` module.
 #[derive(Debug, Any)]
 #[rune(item = ::http)]
 pub struct Error {
@@ -138,6 +148,7 @@ impl Response {
     }
 }
 
+/// An HTTP status code.
 #[derive(Debug, Any)]
 #[rune(item = ::http)]
 pub struct StatusCode {

crates/rune/src/compile/context.rs

@@ -156,6 +156,7 @@ impl Context {
         this.install(crate::modules::io::module(stdio)?)?;
         this.install(crate::modules::iter::module()?)?;
         this.install(crate::modules::macros::module()?)?;
+        this.install(crate::modules::macros::builtin::module()?)?;
         this.install(crate::modules::mem::module()?)?;
         this.install(crate::modules::object::module()?)?;
         this.install(crate::modules::ops::module()?)?;

crates/rune/src/module/module.rs

@@ -422,6 +422,8 @@ impl Module {
     }
 
     /// Modify the current module to utilise a special identifier.
+    ///
+    /// TODO: Deprecate after next major release.
     #[doc(hidden)]
     pub fn with_unique(self, id: &'static str) -> Self {
         Self {

crates/rune/src/modules/any.rs

@@ -1,12 +1,12 @@
-//! The `std::any` rune module.
+//! Dynamic typing and type reflection.
 
 use crate as rune;
 use crate::alloc::fmt::TryWrite;
 use crate::alloc::String;
 use crate::runtime::{Formatter, Type, Value, VmResult};
 use crate::{ContextError, Module};
 
-/// Utilities for dynamic typing or type reflection.
+/// Dynamic typing and type reflection.
 ///
 /// # `Type`
 ///

crates/rune/src/modules/bytes.rs

@@ -1,14 +1,15 @@
-//! The `std::bytes` module.
+//! The bytes module.
 
 use crate as rune;
 use crate::alloc::prelude::*;
 use crate::alloc::Vec;
 use crate::runtime::{Bytes, VmResult};
 use crate::{ContextError, Module};
 
-/// Construct the `std::bytes` module.
+/// The bytes module.
+#[rune::module(::std::bytes)]
 pub fn module() -> Result<Module, ContextError> {
-    let mut module = Module::with_crate_item("std", ["bytes"])?;
+    let mut module = Module::from_meta(self::module_meta)?;
 
     module.ty::<Bytes>()?;
     module.function_meta(new)?;

crates/rune/src/modules/capture_io.rs

@@ -1,5 +1,7 @@
 //! I/O module capable of capturing what's been written to a buffer.
 //!
+//! # Examples
+//!
 //! ```
 //! use rune::{Context, ContextError};
 //! use rune::modules::capture_io::{self, CaptureIo};
@@ -17,15 +19,17 @@ use ::rust_alloc::sync::Arc;
 
 use parking_lot::Mutex;
 
+use crate as rune;
 use crate::alloc::fmt::TryWrite;
 use crate::alloc::string::FromUtf8Error;
 use crate::alloc::{String, Vec};
 use crate::runtime::{Stack, VmError, VmResult};
 use crate::{ContextError, Module, Value};
 
-/// Provide a bunch of `std` functions that can be used during tests to capture output.
+/// I/O module capable of capturing what's been written to a buffer.
+#[rune::module(::std::io)]
 pub fn module(io: &CaptureIo) -> Result<Module, ContextError> {
-    let mut module = Module::with_crate_item("std", ["io"])?;
+    let mut module = Module::from_meta(self::module_meta)?;
 
     let o = io.clone();
 

crates/rune/src/modules/char.rs

@@ -1,4 +1,4 @@
-//! The `std::char` module.
+//! The character module for Rune.
 
 use core::char::ParseCharError;
 
@@ -7,11 +7,12 @@ use crate::{ContextError, Module};
 
 use crate as rune;
 
-/// Construct the `std::char` module.
+/// The character module for Rune.
+#[rune::module(::std::char)]
 pub fn module() -> Result<Module, ContextError> {
-    let mut module = Module::with_crate_item("std", ["char"])?;
-    module.ty::<ParseCharError>()?;
+    let mut module = Module::from_meta(self::module_meta)?;
 
+    module.ty::<ParseCharError>()?;
     module.function_meta(from_i64)?;
     module.function_meta(to_i64)?;
     module.function_meta(is_alphabetic)?;

crates/rune/src/modules/clone.rs

@@ -1,16 +1,16 @@
-//! The `std::clone` module.
+//! The cloning trait for Rune.
 
 use crate as rune;
 use crate::runtime::{Value, VmResult};
 use crate::{ContextError, Module};
 
-#[rune::module(::std::clone)]
-/// The `std::clone` module.
+/// The cloning trait for Rune.
 ///
 /// This module defines methods and types used when cloning values.
 ///
 /// By default all values in rune are structurally shared, so in order to get a
 /// unique instance of it you must call [`clone`] over it.
+#[rune::module(::std::clone)]
 pub fn module() -> Result<Module, ContextError> {
     let mut module = Module::from_meta(self::module_meta)?;
     module.function_meta(clone)?;

crates/rune/src/modules/cmp.rs

@@ -1,4 +1,4 @@
-//! The `std::cmp` module.
+//! Comparison and ordering.
 
 use core::cmp::Ordering;
 
@@ -7,9 +7,10 @@ use crate::alloc::fmt::TryWrite;
 use crate::runtime::{Formatter, Value, VmResult};
 use crate::{ContextError, Module};
 
-/// Construct the `std::cmp` module.
+/// Comparison and ordering.
+#[rune::module(::std::cmp)]
 pub fn module() -> Result<Module, ContextError> {
-    let mut m = Module::with_crate_item("std", ["cmp"])?;
+    let mut m = Module::from_meta(self::module_meta)?;
 
     {
         let ty = m.ty::<Ordering>()?.docs([

crates/rune/src/modules/collections.rs

@@ -1,4 +1,4 @@
-//! `std::collections` module.
+//! Dynamic collections.
 
 #[cfg(feature = "alloc")]
 mod hash_map;
@@ -15,8 +15,8 @@ pub(crate) use self::hash_set::HashSet;
 pub(crate) use self::vec_deque::VecDeque;
 use crate as rune;
 
+/// Dynamic collections.
 #[rune::module(::std::collections)]
-/// The `std::collections` module.
 pub fn module() -> Result<Module, ContextError> {
     let mut module = Module::from_meta(self::module_meta)?;
     #[cfg(feature = "alloc")]

crates/rune/src/modules/core.rs

@@ -1,4 +1,4 @@
-//! The core `std` module.
+//! Core types and methods in Rune.
 
 use crate as rune;
 use crate::alloc::prelude::*;
@@ -9,7 +9,9 @@ use crate::runtime::{Panic, Value, VmResult};
 use crate::{ContextError, Module};
 
 #[rune::module(::std)]
-/// The Rune standard library.
+/// Core types and methods in Rune.
+///
+/// These are types and methods for which Rune as a language would not work without.
 pub fn module() -> Result<Module, ContextError> {
     let mut module = Module::from_meta(self::module_meta)?.with_unique("std");
 

crates/rune/src/modules/disable_io.rs

@@ -1,4 +1,6 @@
-//! I/O module ignoring everything written to output.
+//! I/O methods which will cause any output to be ignored.
+//!
+//! # Examples
 //!
 //! ```
 //! use rune::{Context, ContextError};
@@ -9,15 +11,16 @@
 //! # Ok::<_, ContextError>(())
 //! ```
 
+use crate as rune;
 use crate::runtime::{Stack, VmResult};
 use crate::{ContextError, Module};
 
-/// Provide a bunch of `std::io` functions which will cause any output to be ignored.
+/// I/O methods which will cause any output to be ignored.
+#[rune::module(::std::io)]
 pub fn module() -> Result<Module, ContextError> {
-    let mut module = Module::with_crate_item("std", ["io"])?;
+    let mut module = Module::from_meta(self::module_meta)?;
 
     module.function("print", move |_: &str| {}).build()?;
-
     module.function("println", move |_: &str| {}).build()?;
 
     module

crates/rune/src/modules/f64.rs

@@ -1,4 +1,4 @@
-//! The `std::f64` module.
+//! Floating point numbers.
 
 use core::cmp::Ordering;
 use core::num::ParseFloatError;
@@ -7,9 +7,13 @@ use crate as rune;
 use crate::runtime::{VmErrorKind, VmResult};
 use crate::{ContextError, Module};
 
-/// Install the core package into the given functions namespace.
+/// Floating point numbers.
+///
+/// This provides methods for computing over and parsing 64-bit floating pointer
+/// numbers.
+#[rune::module(::std::f64)]
 pub fn module() -> Result<Module, ContextError> {
-    let mut m = Module::with_crate_item("std", ["f64"])?;
+    let mut m = Module::from_meta(self::module_meta)?;
 
     m.function_meta(parse)?
         .deprecated("Use std::string::parse::<f64> instead")?;

crates/rune/src/modules/fmt.rs

@@ -1,4 +1,4 @@
-//! The `std::fmt` module.
+//! Formatting text.
 
 use core::fmt;
 
@@ -10,9 +10,21 @@ use crate::parse::Parser;
 use crate::runtime::{Format, Formatter, VmResult};
 use crate::{ContextError, Module};
 
-/// Construct the `std::fmt` module.
+/// Formatting text.
+///
+/// This includes types, macros, and functions used to format text.
+///
+/// # Examples
+///
+/// ```rune
+/// let who = "World";
+/// let string = format!("Hello {}", who);
+/// assert_eq!(string, "Hello World");
+/// ```
+#[rune::module(::std::fmt)]
 pub fn module() -> Result<Module, ContextError> {
-    let mut module = Module::with_crate_item("std", ["fmt"])?.with_unique("std::fmt");
+    let mut module = Module::from_meta(self::module_meta)?.with_unique("std::fmt");
+
     module.ty::<Format>()?;
     module.ty::<Formatter>()?;
     module.ty::<fmt::Error>()?;