Deny missing documentation in wasmtime crate (bytecodealliance#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

@@ -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;

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;

crates/api/src/ref.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use std::any::Any;
 use std::cell::{self, RefCell};
 use std::fmt;

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<String>,
@@ -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()
     }

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),
 }
 

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<H>(&self, handler: H)
     where
         H: 'static + Fn(winapi::um::winnt::EXCEPTION_POINTERS) -> bool;