Merge #942

942: Deny missing docs in runtime core and add missing docs r=bjfish a=bjfish

<!-- 
Prior to submitting a PR, review the CONTRIBUTING.md document for recommendations on how to test:
https://github.com/wasmerio/wasmer/blob/master/CONTRIBUTING.md#pull-requests

-->

# Description
Deny missing docs in runtime core and add missing docs
<!-- 
Provide details regarding the change including motivation,
links to related issues, and the context of the PR.
-->

# Review

- [x] Add a short description of the the change to the CHANGELOG.md file


Co-authored-by: Brandon Fish <[email protected]>

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## **[Unreleased]**
 
+- [#942](https://github.com/wasmerio/wasmer/pull/942) Deny missing docs in runtime core and add missing docs
 - [#936](https://github.com/wasmerio/wasmer/pull/939) Fix bug causing attempts to append to files with WASI to delete the contents of the file
 - [#940](https://github.com/wasmerio/wasmer/pull/940) Update supported Rust version to 1.38+
 - [#921](https://github.com/wasmerio/wasmer/pull/921) In LLVM backend, annotate all memory accesses with TBAA metadata.

lib/runtime-core/src/backing.rs

@@ -17,6 +17,7 @@ use crate::{
 };
 use std::{fmt::Debug, slice};
 
+/// Size of the array for internal instance usage
 pub const INTERNALS_SIZE: usize = 256;
 
 pub(crate) struct Internals(pub(crate) [u64; INTERNALS_SIZE]);
@@ -472,6 +473,8 @@ impl LocalBacking {
     }
 }
 
+/// The `ImportBacking` stores references to the imported resources of an Instance. This includes
+/// imported memories, tables, globals and functions.
 #[derive(Debug)]
 pub struct ImportBacking {
     pub(crate) memories: BoxedMap<ImportedMemoryIndex, Memory>,
@@ -488,6 +491,7 @@ pub struct ImportBacking {
 unsafe impl Send for ImportBacking {}
 
 impl ImportBacking {
+    /// Creates a new `ImportBacking` from the given `ModuleInner`, `ImportObject`, and `Ctx`.
     pub fn new(
         module: &ModuleInner,
         imports: &ImportObject,
@@ -536,6 +540,7 @@ impl ImportBacking {
         }
     }
 
+    /// Gets a `ImportedFunc` from the given `ImportedFuncIndex`.
     pub fn imported_func(&self, index: ImportedFuncIndex) -> vm::ImportedFunc {
         self.vm_functions[index].clone()
     }

lib/runtime-core/src/cache.rs

@@ -1,3 +1,7 @@
+//! The cache module provides the common data structures used by compiler backends to allow
+//! serializing compiled wasm code to a binary format.  The binary format can be persisted,
+//! and loaded to allow skipping compilation and fast startup.
+
 use crate::{
     backend::Backend,
     module::{Module, ModuleInfo},
@@ -6,20 +10,31 @@ use crate::{
 use blake2b_simd::blake2bp;
 use std::{fmt, io, mem, slice};
 
+/// Indicates the invalid type of invalid cache file
 #[derive(Debug)]
 pub enum InvalidFileType {
+    /// Given cache header slice does not match the expected size of an `ArtifactHeader`
     InvalidSize,
+    /// Given cache header slice does not contain the expected magic bytes
     InvalidMagic,
 }
 
+/// Kinds of caching errors
 #[derive(Debug)]
 pub enum Error {
+    /// An IO error while reading/writing a cache binary.
     IoError(io::Error),
+    /// An error deserializing bytes into a cache data structure.
     DeserializeError(String),
+    /// An error serializing bytes from a cache data structure.
     SerializeError(String),
+    /// An undefined caching error with a message.
     Unknown(String),
+    /// An invalid cache binary given.
     InvalidFile(InvalidFileType),
+    /// The cached binary has been invalidated.
     InvalidatedCache,
+    /// The current backend does not support caching.
     UnsupportedBackend(Backend),
 }
 
@@ -164,6 +179,8 @@ struct ArtifactInner {
     compiled_code: Memory,
 }
 
+/// Artifact are produced by caching, are serialized/deserialized to binaries, and contain
+/// module info, backend metadata, and compiled code.
 pub struct Artifact {
     inner: ArtifactInner,
 }
@@ -183,6 +200,7 @@ impl Artifact {
         }
     }
 
+    /// Deserializes an `Artifact` from the given byte slice.
     pub fn deserialize(bytes: &[u8]) -> Result<Self, Error> {
         let (_, body_slice) = ArtifactHeader::read_from_slice(bytes)?;
 
@@ -192,6 +210,7 @@ impl Artifact {
         Ok(Artifact { inner })
     }
 
+    /// A reference to the `Artifact`'s stored `ModuleInfo`
     pub fn info(&self) -> &ModuleInfo {
         &self.inner.info
     }
@@ -205,6 +224,7 @@ impl Artifact {
         )
     }
 
+    /// Serializes the `Artifact` into a vector of bytes
     pub fn serialize(&self) -> Result<Vec<u8>, Error> {
         let cache_header = ArtifactHeader {
             magic: WASMER_CACHE_MAGIC,
@@ -230,14 +250,17 @@ impl Artifact {
 ///
 /// The `wasmer-runtime` supplies a naive `FileSystemCache` api.
 pub trait Cache {
+    /// Error type to return when load error occurs
     type LoadError: fmt::Debug;
+    /// Error type to return when store error occurs
     type StoreError: fmt::Debug;
 
     /// loads a module using the default `Backend`
     fn load(&self, key: WasmHash) -> Result<Module, Self::LoadError>;
     /// loads a cached module using a specific `Backend`
     fn load_with_backend(&self, key: WasmHash, backend: Backend)
         -> Result<Module, Self::LoadError>;
+    /// Store a module into the cache with the given key
     fn store(&mut self, key: WasmHash, module: Module) -> Result<(), Self::StoreError>;
 }
 

lib/runtime-core/src/codegen.rs

@@ -1,3 +1,5 @@
+//! The codegen module provides common functions and data structures used by multiple backends
+//! during the code generation process.
 use crate::{
     backend::RunnableModule,
     backend::{Backend, CacheGen, Compiler, CompilerConfig, Features, Token},
@@ -17,22 +19,35 @@ use std::sync::{Arc, RwLock};
 use wasmparser::{self, WasmDecoder};
 use wasmparser::{Operator, Type as WpType};
 
+/// A type that defines a function pointer, which is called when breakpoints occur.
 pub type BreakpointHandler =
     Box<dyn Fn(BreakpointInfo) -> Result<(), Box<dyn Any>> + Send + Sync + 'static>;
+
+/// Maps instruction pointers to their breakpoint handlers.
 pub type BreakpointMap = Arc<HashMap<usize, BreakpointHandler>>;
 
+/// An event generated during parsing of a wasm binary
 #[derive(Debug)]
 pub enum Event<'a, 'b> {
+    /// An internal event created by the parser used to provide hooks during code generation.
     Internal(InternalEvent),
+    /// An event generated by parsing a wasm operator
     Wasm(&'b Operator<'a>),
+    /// An event generated by parsing a wasm operator that contains an owned `Operator`
     WasmOwned(Operator<'a>),
 }
 
+/// Kinds of `InternalEvent`s created during parsing.
 pub enum InternalEvent {
+    /// A function parse is about to begin.
     FunctionBegin(u32),
+    /// A function parsing has just completed.
     FunctionEnd,
+    /// A breakpoint emitted during parsing.
     Breakpoint(BreakpointHandler),
+    /// Indicates setting an internal field.
     SetInternal(u32),
+    /// Indicates getting an internal field.
     GetInternal(u32),
 }
 
@@ -48,10 +63,13 @@ impl fmt::Debug for InternalEvent {
     }
 }
 
+/// Information for a breakpoint
 pub struct BreakpointInfo<'a> {
+    /// Fault.
     pub fault: Option<&'a dyn Any>,
 }
 
+/// A trait that represents the functions needed to be implemented to generate code for a module.
 pub trait ModuleCodeGenerator<FCG: FunctionCodeGenerator<E>, RM: RunnableModule, E: Debug> {
     /// Creates a new module code generator.
     fn new() -> Self;
@@ -65,7 +83,7 @@ pub trait ModuleCodeGenerator<FCG: FunctionCodeGenerator<E>, RM: RunnableModule,
     }
     /// Adds an import function.
     fn feed_import_function(&mut self) -> Result<(), E>;
-
+    /// Sets the signatures.
     fn feed_signatures(&mut self, signatures: Map<SigIndex, FuncSig>) -> Result<(), E>;
     /// Sets function signatures.
     fn feed_function_signatures(&mut self, assoc: Map<FuncIndex, SigIndex>) -> Result<(), E>;
@@ -80,6 +98,8 @@ pub trait ModuleCodeGenerator<FCG: FunctionCodeGenerator<E>, RM: RunnableModule,
     unsafe fn from_cache(cache: Artifact, _: Token) -> Result<ModuleInner, CacheError>;
 }
 
+/// A streaming compiler which is designed to generated code for a module based on a stream
+/// of wasm parser events.
 pub struct StreamingCompiler<
     MCG: ModuleCodeGenerator<FCG, RM, E>,
     FCG: FunctionCodeGenerator<E>,
@@ -94,6 +114,7 @@ pub struct StreamingCompiler<
     _phantom_e: PhantomData<E>,
 }
 
+/// A simple generator for a `StreamingCompiler`.
 pub struct SimpleStreamingCompilerGen<
     MCG: ModuleCodeGenerator<FCG, RM, E>,
     FCG: FunctionCodeGenerator<E>,
@@ -113,6 +134,7 @@ impl<
         E: Debug,
     > SimpleStreamingCompilerGen<MCG, FCG, RM, E>
 {
+    /// Create a new `StreamingCompiler`.
     pub fn new() -> StreamingCompiler<MCG, FCG, RM, E, impl Fn() -> MiddlewareChain> {
         StreamingCompiler::new(|| MiddlewareChain::new())
     }
@@ -126,6 +148,7 @@ impl<
         CGEN: Fn() -> MiddlewareChain,
     > StreamingCompiler<MCG, FCG, RM, E, CGEN>
 {
+    /// Create a new `StreamingCompiler` with the given `MiddlewareChain`.
     pub fn new(chain_gen: CGEN) -> Self {
         Self {
             middleware_chain_generator: chain_gen,
@@ -137,6 +160,7 @@ impl<
     }
 }
 
+/// Create a new `ValidatingParserConfig` with the given features.
 pub fn validating_parser_config(features: &Features) -> wasmparser::ValidatingParserConfig {
     wasmparser::ValidatingParserConfig {
         operator_config: wasmparser::OperatorValidatorConfig {
@@ -220,29 +244,35 @@ fn requires_pre_validation(backend: Backend) -> bool {
     }
 }
 
+/// A sink for parse events.
 pub struct EventSink<'a, 'b> {
     buffer: SmallVec<[Event<'a, 'b>; 2]>,
 }
 
 impl<'a, 'b> EventSink<'a, 'b> {
+    /// Push a new `Event` to this sink.
     pub fn push(&mut self, ev: Event<'a, 'b>) {
         self.buffer.push(ev);
     }
 }
 
+/// A container for a chain of middlewares.
 pub struct MiddlewareChain {
     chain: Vec<Box<dyn GenericFunctionMiddleware>>,
 }
 
 impl MiddlewareChain {
+    /// Create a new empty `MiddlewareChain`.
     pub fn new() -> MiddlewareChain {
         MiddlewareChain { chain: vec![] }
     }
 
+    /// Push a new `FunctionMiddleware` to this `MiddlewareChain`.
     pub fn push<M: FunctionMiddleware + 'static>(&mut self, m: M) {
         self.chain.push(Box::new(m));
     }
 
+    /// Run this chain with the provided function code generator, event and module info.
     pub(crate) fn run<E: Debug, FCG: FunctionCodeGenerator<E>>(
         &mut self,
         fcg: Option<&mut FCG>,
@@ -270,8 +300,11 @@ impl MiddlewareChain {
     }
 }
 
+/// A trait that represents the signature required to implement middleware for a function.
 pub trait FunctionMiddleware {
+    /// The error type for this middleware's functions.
     type Error: Debug;
+    /// Processes the given event, module info and sink.
     fn feed_event<'a, 'b: 'a>(
         &mut self,
         op: Event<'a, 'b>,