Way more documentation

benches/benches/bench_main.rs

@@ -23,10 +23,10 @@ pub(crate) fn sources(source: &str) -> Sources {
 
 macro_rules! rune_vm {
     ($($tt:tt)*) => {{
-        let context = rune::Context::with_default_modules().expect("failed to build context");
+        let context = rune::Context::with_default_modules().expect("Failed to build context");
         let mut diagnostics = Default::default();
         let mut sources = $crate::sources(stringify!($($tt)*));
-        $crate::vm(&context, &mut sources, &mut diagnostics).expect("program to compile successfully")
+        $crate::vm(&context, &mut sources, &mut diagnostics).expect("Program to compile successfully")
     }};
 }
 

crates/rune/src/cli.rs

@@ -118,7 +118,7 @@ impl<'a> Entry<'a> {
         let runtime = tokio::runtime::Builder::new_current_thread()
             .enable_all()
             .build()
-            .expect("failed to build runtime");
+            .expect("Failed to build runtime");
 
         match runtime.block_on(self.inner()) {
             Ok(exit_code) => {

crates/rune/src/cli/loader.rs

@@ -45,11 +45,11 @@ pub(super) fn load(
 
         match bincode::deserialize_from::<_, Unit>(f) {
             Ok(unit) => {
-                tracing::trace!("using cache: {}", bytecode_path.display());
+                tracing::trace!("Using cache: {}", bytecode_path.display());
                 Some(Arc::new(unit))
             }
             Err(e) => {
-                tracing::error!("failed to deserialize: {}: {}", bytecode_path.display(), e);
+                tracing::error!("Failed to deserialize: {}: {}", bytecode_path.display(), e);
                 None
             }
         }

crates/rune/src/compile/context.rs

@@ -438,6 +438,8 @@ impl Context {
                                 #[cfg(feature = "doc")]
                                 is_async: false,
                                 #[cfg(feature = "doc")]
+                                deprecated: None,
+                                #[cfg(feature = "doc")]
                                 args: Some(match fields {
                                     Fields::Named(names) => names.len(),
                                     Fields::Unnamed(args) => *args,
@@ -500,6 +502,8 @@ impl Context {
                                 #[cfg(feature = "doc")]
                                 is_async: false,
                                 #[cfg(feature = "doc")]
+                                deprecated: None,
+                                #[cfg(feature = "doc")]
                                 args: Some(match fields {
                                     Fields::Named(names) => names.len(),
                                     Fields::Unnamed(args) => *args,
@@ -615,6 +619,8 @@ impl Context {
             #[cfg(feature = "doc")]
             is_async: f.is_async,
             #[cfg(feature = "doc")]
+            deprecated: f.deprecated.clone(),
+            #[cfg(feature = "doc")]
             args: f.args,
             #[cfg(feature = "doc")]
             return_type: f.return_type.as_ref().map(|f| f.hash),
@@ -722,6 +728,8 @@ impl Context {
             #[cfg(feature = "doc")]
             is_async: assoc.is_async,
             #[cfg(feature = "doc")]
+            deprecated: assoc.deprecated.clone(),
+            #[cfg(feature = "doc")]
             args: assoc.args,
             #[cfg(feature = "doc")]
             return_type: assoc.return_type.as_ref().map(|f| f.hash),
@@ -802,6 +810,8 @@ impl Context {
             #[cfg(feature = "doc")]
             is_async: false,
             #[cfg(feature = "doc")]
+            deprecated: None,
+            #[cfg(feature = "doc")]
             args: Some(0),
             #[cfg(feature = "doc")]
             return_type: Some(hash),
@@ -892,6 +902,8 @@ impl Context {
                     #[cfg(feature = "doc")]
                     is_async: false,
                     #[cfg(feature = "doc")]
+                    deprecated: None,
+                    #[cfg(feature = "doc")]
                     args: Some(match fields {
                         Fields::Named(names) => names.len(),
                         Fields::Unnamed(args) => *args,

crates/rune/src/compile/meta.rs

@@ -326,6 +326,9 @@ pub struct Signature {
     /// An asynchronous function.
     #[cfg(feature = "doc")]
     pub(crate) is_async: bool,
+    /// Deprecation notice.
+    #[cfg(feature = "doc")]
+    pub(crate) deprecated: Option<Box<str>>,
     /// Arguments.
     #[cfg(feature = "doc")]
     pub(crate) args: Option<usize>,

crates/rune/src/doc/build.rs

@@ -812,6 +812,7 @@ fn module<'m>(cx: &mut Ctxt<'_, 'm>, meta: Meta<'m>, queue: &mut VecDeque<Build<
     #[derive(Serialize)]
     struct Function<'a> {
         is_async: bool,
+        deprecated: Option<&'a str>,
         path: RelativePathBuf,
         #[serde(serialize_with = "serialize_item")]
         item: ItemBuf,
@@ -895,6 +896,7 @@ fn module<'m>(cx: &mut Ctxt<'_, 'm>, meta: Meta<'m>, queue: &mut VecDeque<Build<
 
                     functions.push(Function {
                         is_async: f.is_async,
+                        deprecated: f.deprecated,
                         path: cx.item_path(&item, ItemKind::Function)?,
                         item: item.clone(),
                         name,
@@ -979,6 +981,7 @@ fn build_function<'m>(cx: &mut Ctxt<'_, 'm>, meta: Meta<'m>) -> Result<Builder<'
         shared: Shared<'a>,
         module: String,
         is_async: bool,
+        deprecated: Option<&'a str>,
         #[serde(serialize_with = "serialize_item")]
         item: &'a Item,
         #[serde(serialize_with = "serialize_component_ref")]
@@ -1011,6 +1014,7 @@ fn build_function<'m>(cx: &mut Ctxt<'_, 'm>, meta: Meta<'m>) -> Result<Builder<'
             shared: cx.shared(),
             module: cx.module_path_html(meta, false)?,
             is_async: f.is_async,
+            deprecated: f.deprecated,
             item,
             name,
             args: cx.args_to_string(f.arg_names, f.args, f.signature, f.argument_types)?,

crates/rune/src/doc/build/type_.rs

@@ -19,6 +19,7 @@ pub(super) struct Protocol<'a> {
 #[derive(Serialize)]
 pub(super) struct Method<'a> {
     is_async: bool,
+    deprecated: Option<&'a str>,
     name: &'a str,
     args: String,
     parameters: Option<String>,
@@ -90,6 +91,7 @@ pub(super) fn build_assoc_fns<'m>(
 
                         methods.push(Method {
                             is_async: assoc.is_async,
+                            deprecated: assoc.deprecated,
                             name,
                             args: cx.args_to_string(
                                 assoc.arg_names,

crates/rune/src/doc/context.rs

@@ -33,6 +33,7 @@ pub(crate) struct Meta<'a> {
 #[derive(Debug, Clone, Copy)]
 pub(crate) struct Function<'a> {
     pub(crate) is_async: bool,
+    pub(crate) deprecated: Option<&'a str>,
     pub(crate) arg_names: Option<&'a [String]>,
     pub(crate) args: Option<usize>,
     pub(crate) signature: Signature,
@@ -64,6 +65,7 @@ pub(crate) struct AssocVariant<'a> {
 pub(crate) struct AssocFn<'a> {
     pub(crate) kind: AssocFnKind<'a>,
     pub(crate) is_async: bool,
+    pub(crate) deprecated: Option<&'a str>,
     pub(crate) return_type: Option<Hash>,
     pub(crate) argument_types: &'a [Option<Hash>],
     pub(crate) docs: &'a [String],
@@ -125,19 +127,21 @@ impl<'a> Context<'a> {
             Some(associated.iter().flat_map(move |hash| {
                 let data = visitor.data.get(hash)?;
 
-                let (is_async, kind) = match data.kind {
+                let (is_async, deprecated, kind) = match data.kind {
                     Some(meta::Kind::Function {
                         signature: ref f,
                         ..
                     }) => (
                         f.is_async,
+                        f.deprecated.as_deref(),
                         AssocFnKind::Method(data.item.last()?.as_str()?, f.args, Signature::Function),
                     ),
                     Some(meta::Kind::AssociatedFunction {
                         signature: ref f,
                         ..
                     }) => (
                         f.is_async,
+                        f.deprecated.as_deref(),
                         AssocFnKind::Method(data.item.last()?.as_str()?, f.args, Signature::Instance),
                     ),
                     Some(meta::Kind::Variant { .. }) => {
@@ -152,6 +156,7 @@ impl<'a> Context<'a> {
                 Some(Assoc::Fn(AssocFn {
                     kind,
                     is_async,
+                    deprecated,
                     return_type: None,
                     argument_types: &[],
                     docs: &data.docs,
@@ -184,6 +189,7 @@ impl<'a> Context<'a> {
                     Some(Assoc::Fn(AssocFn {
                         kind,
                         is_async: signature.is_async,
+                        deprecated: signature.deprecated.as_deref(),
                         return_type: signature.return_type,
                         argument_types: &signature
                             .argument_types,
@@ -198,6 +204,7 @@ impl<'a> Context<'a> {
                     Some(Assoc::Fn(AssocFn {
                         kind,
                         is_async: signature.is_async,
+                        deprecated: signature.deprecated.as_deref(),
                         return_type: signature.return_type,
                         argument_types: &signature
                             .argument_types,
@@ -288,6 +295,7 @@ impl<'a> Context<'a> {
             } => {
                 Kind::Function(Function {
                     is_async: f.is_async,
+                    deprecated: f.deprecated.as_deref(),
                     signature: Signature::Function,
                     arg_names: meta.docs.args(),
                     args: f.args,
@@ -301,6 +309,7 @@ impl<'a> Context<'a> {
             } => {
                 Kind::Function(Function {
                     is_async: f.is_async,
+                    deprecated: f.deprecated.as_deref(),
                     signature: Signature::Instance,
                     arg_names: meta.docs.args(),
                     args: f.args,
@@ -343,6 +352,7 @@ fn visitor_meta_to_meta<'a>(base: &'a Item, data: &'a VisitorData) -> Meta<'a> {
         Some(meta::Kind::Enum { .. }) => Kind::Enum,
         Some(meta::Kind::Function { signature: f, .. }) => Kind::Function(Function {
             is_async: f.is_async,
+            deprecated: f.deprecated.as_deref(),
             arg_names: None,
             args: f.args,
             signature: Signature::Function,
@@ -351,6 +361,7 @@ fn visitor_meta_to_meta<'a>(base: &'a Item, data: &'a VisitorData) -> Meta<'a> {
         }),
         Some(meta::Kind::AssociatedFunction { signature: f, .. }) => Kind::Function(Function {
             is_async: f.is_async,
+            deprecated: f.deprecated.as_deref(),
             arg_names: None,
             args: f.args,
             signature: Signature::Instance,

crates/rune/src/doc/static/function.html.hbs

@@ -4,5 +4,6 @@
 <div class="signature">
 {{#if is_async}}<span class="keyword async">async</span> {{/if}} <span class="keyword fn">fn</span> <span class="fn">{{name}}</span>({{literal args}}){{#if this.return_type}} -&gt; {{literal this.return_type}}{{/if}}</h3>
 </div>
+{{#if deprecated}}<div class="deprecated"><span class="heading">Deprecated:</span><span class="content">{{deprecated}}</span></div>{{/if}}
 {{#if doc}}{{literal doc}}{{/if}}
 {{/layout}}

crates/rune/src/doc/static/runedoc.css.hbs

@@ -18,6 +18,8 @@
     --keyword-async-color: rgb(70, 43, 241);
     --code-background-color: rgb(42, 42, 42);
     --code-block-background-color: #2a2a2a;
+    --deprecated-color: #39261c;
+    --deprecated-background-color: #da9347;
 }
 
 @font-face {
@@ -174,6 +176,21 @@ pre, .signature {
     padding: 14px;
 }
 
+.deprecated {
+    color: var(--deprecated-color);
+    background-color: var(--deprecated-background-color);
+    border-radius: 3px;
+    padding: 0.1em 0.2em;
+    font-size: 80%;
+    margin-top: 0.5em;
+    margin-bottom: 0.5em;
+}
+
+.deprecated .heading {
+    font-weight: bold;
+    margin-right: 0.5em;
+}
+
 p > code {
     background-color: var(--code-block-background-color);
     border-radius: 3px;

crates/rune/src/doc/static/type.html.hbs

@@ -9,6 +9,7 @@
     <div class="item item-fn">
         <div id="method.{{this.name}}" class="item-title">
         {{#if this.is_async}}<span class="async">async</span> {{/if}}fn <a href="#method.{{this.name}}" class="fn">{{this.name}}</a>{{#if this.parameters}}&lt;{{literal this.parameters}}&gt;{{/if}}({{literal this.args}}){{#if this.return_type}} -&gt; {{literal this.return_type}}{{/if}}
+        {{#if this.deprecated}}<div class="deprecated"><span class="heading">Deprecated:</span><span class="content">{{this.deprecated}}</span></div>{{/if}}
         </div>
         {{#if this.doc}}{{literal this.doc}}{{/if}}
     </div>

crates/rune/src/module.rs

@@ -200,6 +200,8 @@ pub(crate) struct ModuleFunction {
     #[cfg(feature = "doc")]
     pub(crate) is_async: bool,
     #[cfg(feature = "doc")]
+    pub(crate) deprecated: Option<Box<str>>,
+    #[cfg(feature = "doc")]
     pub(crate) args: Option<usize>,
     #[cfg(feature = "doc")]
     pub(crate) return_type: Option<FullTypeOf>,
@@ -217,6 +219,8 @@ pub(crate) struct ModuleAssociated {
     #[cfg(feature = "doc")]
     pub(crate) is_async: bool,
     #[cfg(feature = "doc")]
+    pub(crate) deprecated: Option<Box<str>>,
+    #[cfg(feature = "doc")]
     pub(crate) args: Option<usize>,
     #[cfg(feature = "doc")]
     pub(crate) return_type: Option<FullTypeOf>,
@@ -291,6 +295,8 @@ pub struct ItemFnMut<'a> {
     #[cfg(feature = "doc")]
     is_async: &'a mut bool,
     #[cfg(feature = "doc")]
+    deprecated: &'a mut Option<Box<str>>,
+    #[cfg(feature = "doc")]
     args: &'a mut Option<usize>,
     #[cfg(feature = "doc")]
     return_type: &'a mut Option<FullTypeOf>,
@@ -321,6 +327,22 @@ impl ItemFnMut<'_> {
         self
     }
 
+    /// Mark the given item as deprecated.
+    pub fn deprecated<S>(
+        self,
+        #[cfg_attr(not(feature = "doc"), allow(unused))] deprecated: S,
+    ) -> Self
+    where
+        S: AsRef<str>,
+    {
+        #[cfg(feature = "doc")]
+        {
+            *self.deprecated = Some(deprecated.as_ref().into());
+        }
+
+        self
+    }
+
     /// Indicate the number of arguments this function accepts.
     pub fn args(self, #[cfg_attr(not(feature = "doc"), allow(unused))] args: usize) -> Self {
         #[cfg(feature = "doc")]

crates/rune/src/module/function_meta.rs

@@ -54,6 +54,8 @@ pub struct FunctionData {
     #[cfg(feature = "doc")]
     pub(crate) is_async: bool,
     #[cfg(feature = "doc")]
+    pub(crate) deprecated: Option<Box<str>>,
+    #[cfg(feature = "doc")]
     pub(crate) args: Option<usize>,
     #[cfg(feature = "doc")]
     pub(crate) return_type: Option<FullTypeOf>,
@@ -78,6 +80,8 @@ impl FunctionData {
             #[cfg(feature = "doc")]
             is_async: K::is_async(),
             #[cfg(feature = "doc")]
+            deprecated: None,
+            #[cfg(feature = "doc")]
             args: Some(F::args()),
             #[cfg(feature = "doc")]
             return_type: F::Return::maybe_type_of(),
@@ -212,6 +216,8 @@ pub struct AssociatedFunctionData {
     #[cfg(feature = "doc")]
     pub(crate) is_async: bool,
     #[cfg(feature = "doc")]
+    pub(crate) deprecated: Option<Box<str>>,
+    #[cfg(feature = "doc")]
     pub(crate) args: Option<usize>,
     #[cfg(feature = "doc")]
     pub(crate) return_type: Option<FullTypeOf>,
@@ -236,6 +242,8 @@ impl AssociatedFunctionData {
             #[cfg(feature = "doc")]
             is_async: K::is_async(),
             #[cfg(feature = "doc")]
+            deprecated: None,
+            #[cfg(feature = "doc")]
             args: Some(F::args()),
             #[cfg(feature = "doc")]
             return_type: F::Return::maybe_type_of(),
@@ -337,6 +345,8 @@ where
             #[cfg(feature = "doc")]
             is_async: K::is_async(),
             #[cfg(feature = "doc")]
+            deprecated: None,
+            #[cfg(feature = "doc")]
             args: Some(F::args()),
             #[cfg(feature = "doc")]
             return_type: F::Return::maybe_type_of(),