Use document-features.

Cargo.toml

@@ -35,45 +35,87 @@ unicode-xid = { version = "0.2", default-features = false, optional = true }
 rust_decimal = { version = "1.16", default-features = false, features = ["maths"], optional = true }
 getrandom = { version = "0.2", optional = true }
 rustyline = { version = "10", optional = true }
+document-features = { version = "0.2", optional = true }
 
 [dev-dependencies]
 rmp-serde = "1.1"
 serde_json = { version = "1.0", default-features = false, features = ["alloc"] }
 
 [features]
+
+## Default features: `std`, uses runtime random numbers for hashing.
 default = ["std", "ahash/runtime-rng"]  # ahash/runtime-rng trumps ahash/compile-time-rng
+## Standard features: uses compile-time random number for hashing.
 std = ["ahash/std", "num-traits/std", "smartstring/std"]
-unchecked = []                  # disable safety checks
-sync = []                       # restrict to only types that implement Send + Sync
-no_position = []                # do not track position in the parser
-no_optimize = []                # no script optimizer
-no_float = []                   # no floating-point
-f32_float = []                  # set FLOAT=f32
-only_i32 = []                   # set INT=i32 (useful for 32-bit systems)
-only_i64 = []                   # set INT=i64 (default) and disable support for all other integer types
-decimal = ["rust_decimal"]      # add the Decimal number type
-no_index = []                   # no arrays and indexing
-no_object = []                  # no custom objects
-no_time = []                    # no timestamps
-no_function = ["no_closure"]    # no script-defined functions (meaning no closures)
-no_closure = []                 # no automatic sharing and capture of anonymous functions to external variables
-no_module = []                  # no modules
-no_custom_syntax = []           # no custom syntax or custom operators
-unicode-xid-ident = ["unicode-xid"] # allow Unicode Standard Annex #31 for identifiers.
-metadata = ["serde", "serde_json", "rhai_codegen/metadata", "smartstring/serde"] # enable exporting functions metadata
-internals = []                  # expose internal data structures
-debugging = ["internals"]       # enable debugging
-serde = ["dep:serde", "smartstring/serde", "smallvec/serde"] # implement serde for rhai types
 
-# compiling for no-std
+#! ### Enable Special Functionalities
-no_std = ["no-std-compat", "num-traits/libm", "core-error", "libm", "hashbrown", "no_time"]
 
-# compiling for WASM
+    ## Require that all data types implement `Send + Sync` (for multi-threaded usage).
-wasm-bindgen = ["getrandom/js", "instant/wasm-bindgen"]
+    sync = []
-stdweb = ["getrandom/js", "instant/stdweb"]
+    ## Add support for the [`Decimal`](https://crates.io/crates/rust_decimal) data type (acts as the system floating-point type under `no_float`).
+    decimal = ["rust_decimal"]
+    ## Enable serialization/deserialization of Rhai data types via [`serde`](https://crates.io/crates/serde).
+    serde = ["dep:serde", "smartstring/serde", "smallvec/serde"]
+    ## Allow [Unicode Standard Annex #31](https://unicode.org/reports/tr31/) for identifiers.
+    unicode-xid-ident = ["unicode-xid"]
+    ## Enable functions metadata (including doc-comments); implies [`serde`](#feature-serde).
+    metadata = ["serde", "serde_json", "rhai_codegen/metadata", "smartstring/serde"]
+    ## Expose internal data structures (e.g. `AST` nodes).
+    internals = []
+    ## Enable the debugging interface (implies [`internals`](#feature-internals)).
+    debugging = ["internals"]
+    ## Features and dependencies required by `bin` tools: `decimal`, `metadata`, `serde`, `debugging` and [`rustyline`](https://crates.io/crates/rustyline).
+    bin-features = ["decimal", "metadata", "serde", "debugging", "rustyline"]
 
-# compiling bin tools
+#! ### System Configuration Features
-bin-features = ["decimal", "metadata", "serde", "debugging", "rustyline"]
+
+    ## Use `f32` instead of `f64` as the system floating-point number type.
+    f32_float = []
+    ## Use `i32` instead of `i64` for the system integer number type (useful for 32-bit architectures).
+    ## All other integer types (e.g. `u8`) are disabled.
+    only_i32 = []
+    ## Disable all integer types (e.g. `u8`) other than `i64`.
+    only_i64 = []
+
+#! ### Disable Language Features
+
+    ## Remove support for floating-point numbers.
+    no_float = []
+    ## Remove support for arrays and indexing.
+    no_index = []
+    ## Remove support for custom types, properties, method-style calls and object maps.
+    no_object = []
+    ## Remove support for time-stamps.
+    no_time = []
+    ## Remove support for script-defined functions (implies [`no_closure`](#feature-no_closure)).
+    no_function = ["no_closure"]
+    ## Remove support for capturing external variables in anonymous functions (i.e. closures).
+    no_closure = []
+    ## Remove support for loading external modules.
+    no_module = []
+    ## Remove support for custom syntax.
+    no_custom_syntax = []
+
+#! ### Performance-Related Features
+
+    ## Disable all safety checks.
+    unchecked = []
+    ## Do not track position when parsing.
+    no_position = []
+    ## Disable the script optimizer.
+    no_optimize = []
+
+#! ### Compiling for `no-std`
+
+    ## Turn on `no-std` compilation (nightly only).
+    no_std = ["no-std-compat", "num-traits/libm", "core-error", "libm", "hashbrown", "no_time"]
+
+#! ### JavaScript Interface for WASM
+
+    ## Use [`wasm-bindgen`](https://crates.io/crates/wasm-bindgen) as JavaScript interface.
+    wasm-bindgen = ["getrandom/js", "instant/wasm-bindgen"]
+    ## Use [`stdweb`](https://crates.io/crates/stdweb) as JavaScript interface.
+    stdweb = ["getrandom/js", "instant/stdweb"]
 
 [[bin]]
 name = "rhai-repl"
@@ -104,7 +146,7 @@ codegen-units = 1
 instant = { version = "0.1.10" } # WASM implementation of std::time::Instant
 
 [package.metadata.docs.rs]
-features = ["metadata", "serde", "internals", "decimal", "debugging"]
+features = ["document-features", "metadata", "serde", "internals", "decimal", "debugging"]
 
 [patch.crates-io]
 # Notice that a custom modified version of `rustyline` is used which supports bracketed paste on Windows.

src/lib.rs

@@ -52,7 +52,11 @@
 //! }
 //! ```
 //!
-//! # Documentation
+//! # Features
+//!
+#![cfg_attr(feature = "document-features", doc = document_features::document_features!(feature_label = "<span id=\"feature-{feature}\">**`{feature}`**</span>"))]
+//!
+//! # On-Line Documentation
 //!
 //! See [The Rhai Book](https://rhai.rs/book) for details on the Rhai scripting engine and language.