From 448faed5ca0e38c3ee5cdbe703b9f89f1e76e8a0 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Fri, 17 Jan 2020 12:36:57 -0600 Subject: [PATCH] Deny missing documentation in `wasmtime` crate (#836) * Deny missing documentation in `wasmtime` crate Everything is largely documented now, so let's be sure to keep it that way! * Add windows docs --- crates/api/src/lib.rs | 2 ++ crates/api/src/module.rs | 1 + crates/api/src/ref.rs | 2 ++ crates/api/src/trap.rs | 47 ++++++++++++++++++++++++++++----------- crates/api/src/types.rs | 4 ++++ crates/api/src/windows.rs | 4 +++- 6 files changed, 46 insertions(+), 14 deletions(-) diff --git a/crates/api/src/lib.rs b/crates/api/src/lib.rs index 63e41fb572..0858b7e971 100644 --- a/crates/api/src/lib.rs +++ b/crates/api/src/lib.rs @@ -6,6 +6,8 @@ //! and there to implement Rust idioms. This crate also defines the actual C API //! itself for consumption from other languages. +#![deny(missing_docs)] + mod callable; mod externals; mod instance; diff --git a/crates/api/src/module.rs b/crates/api/src/module.rs index f901a83762..25c9403600 100644 --- a/crates/api/src/module.rs +++ b/crates/api/src/module.rs @@ -218,6 +218,7 @@ impl Module { validate(binary, Some(config)).map_err(Error::new) } + #[doc(hidden)] pub fn from_exports(store: &Store, exports: Box<[ExportType]>) -> Self { let mut ret = Module::empty(store); Rc::get_mut(&mut ret.inner).unwrap().exports = exports; diff --git a/crates/api/src/ref.rs b/crates/api/src/ref.rs index 52f14e6a83..f5dbd2ee42 100644 --- a/crates/api/src/ref.rs +++ b/crates/api/src/ref.rs @@ -1,3 +1,5 @@ +#![allow(missing_docs)] + use std::any::Any; use std::cell::{self, RefCell}; use std::fmt; diff --git a/crates/api/src/trap.rs b/crates/api/src/trap.rs index 653fd0abe2..d68071d7c5 100644 --- a/crates/api/src/trap.rs +++ b/crates/api/src/trap.rs @@ -1,4 +1,3 @@ -use crate::instance::Instance; use backtrace::Backtrace; use std::fmt; use std::sync::Arc; @@ -61,6 +60,8 @@ impl Trap { &self.inner.message } + /// Returns a list of function frames in WebAssembly code that led to this + /// trap happening. pub fn trace(&self) -> &[FrameInfo] { &self.inner.wasm_trace } @@ -102,6 +103,11 @@ impl fmt::Display for Trap { impl std::error::Error for Trap {} +/// Description of a frame in a backtrace for a [`Trap`]. +/// +/// Whenever a WebAssembly trap occurs an instance of [`Trap`] is created. Each +/// [`Trap`] has a backtrace of the WebAssembly frames that led to the trap, and +/// each frame is described by this structure. #[derive(Debug)] pub struct FrameInfo { module_name: Option, @@ -110,26 +116,41 @@ pub struct FrameInfo { } impl FrameInfo { - pub fn instance(&self) -> *const Instance { - unimplemented!("FrameInfo::instance"); - } - + /// Returns the WebAssembly function index for this frame. + /// + /// This function index is the index in the function index space of the + /// WebAssembly module that this frame comes from. pub fn func_index(&self) -> u32 { self.func_index } - pub fn func_offset(&self) -> usize { - unimplemented!("FrameInfo::func_offset"); - } - - pub fn module_offset(&self) -> usize { - unimplemented!("FrameInfo::module_offset"); - } - + /// Returns the identifer of the module that this frame is for. + /// + /// Module identifiers are present in the `name` section of a WebAssembly + /// binary, but this may not return the exact item in the `name` section. + /// Module names can be overwritten at construction time or perhaps inferred + /// from file names. The primary purpose of this function is to assist in + /// debugging and therefore may be tweaked over time. + /// + /// This function returns `None` when no name can be found or inferred. pub fn module_name(&self) -> Option<&str> { self.module_name.as_deref() } + /// Returns a descriptive name of the function for this frame, if one is + /// available. + /// + /// The name of this function may come from the `name` section of the + /// WebAssembly binary, or wasmtime may try to infer a better name for it if + /// not available, for example the name of the export if it's exported. + /// + /// This return value is primarily used for debugging and human-readable + /// purposes for things like traps. Note that the exact return value may be + /// tweaked over time here and isn't guaranteed to be something in + /// particular about a wasm module due to its primary purpose of assisting + /// in debugging. + /// + /// This function returns `None` when no name could be inferred. pub fn func_name(&self) -> Option<&str> { self.func_name.as_deref() } diff --git a/crates/api/src/types.rs b/crates/api/src/types.rs index b8361352f6..b5f9086875 100644 --- a/crates/api/src/types.rs +++ b/crates/api/src/types.rs @@ -116,9 +116,13 @@ impl ValType { /// can either be imported or exported. #[derive(Debug, Clone)] pub enum ExternType { + /// This external type is the type of a WebAssembly function. Func(FuncType), + /// This external type is the type of a WebAssembly global. Global(GlobalType), + /// This external type is the type of a WebAssembly table. Table(TableType), + /// This external type is the type of a WebAssembly memory. Memory(MemoryType), } diff --git a/crates/api/src/windows.rs b/crates/api/src/windows.rs index 11ce1bbec0..aaee1314de 100644 --- a/crates/api/src/windows.rs +++ b/crates/api/src/windows.rs @@ -13,7 +13,9 @@ use crate::Instance; /// Extensions for the [`Instance`] type only available on Windows. pub trait InstanceExt { - // TODO: docs? + /// Configures a custom signal handler to execute. + /// + /// TODO: needs more documentation. unsafe fn set_signal_handler(&self, handler: H) where H: 'static + Fn(winapi::um::winnt::EXCEPTION_POINTERS) -> bool;