From f905dc914b321d2bce979724d177c5653431f1bf Mon Sep 17 00:00:00 2001
From: Dan Gohman <sunfish@mozilla.com>
Date: Mon, 28 Aug 2017 17:07:28 -0700
Subject: [PATCH] Enable missing_docs errors in the wasm crate.

This adds `#![deny(missing_docs)]` to the wasm crate, and adds documentation
to several struct and enum fields, as needed.
---
 lib/wasm/src/lib.rs               |  2 ++
 lib/wasm/src/module_translator.rs | 14 +++++++++-----
 lib/wasm/src/translation_utils.rs | 16 +++++++++++++++-
 3 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/lib/wasm/src/lib.rs b/lib/wasm/src/lib.rs
index 5006e5c9aa..bb342bf7c6 100644
--- a/lib/wasm/src/lib.rs
+++ b/lib/wasm/src/lib.rs
@@ -10,6 +10,8 @@
 //!
 //! The main function of this module is [`translate_module`](fn.translate_module.html).
 
+#![deny(missing_docs)]
+
 extern crate wasmparser;
 extern crate cton_frontend;
 extern crate cretonne;
diff --git a/lib/wasm/src/module_translator.rs b/lib/wasm/src/module_translator.rs
index 1c22655300..10dbbbc43b 100644
--- a/lib/wasm/src/module_translator.rs
+++ b/lib/wasm/src/module_translator.rs
@@ -12,22 +12,25 @@ use cton_frontend::ILBuilder;
 use std::collections::HashMap;
 use runtime::WasmRuntime;
 
-/// Output of the [`translate_module`](fn.translate_module.html) function. Contains the translated
-/// functions and when present the index of the function defined as `start` of the module.
+/// Output of the [`translate_module`](fn.translate_module.html) function.
 pub struct TranslationResult {
+    /// The translated functions.
     pub functions: Vec<FunctionTranslation>,
+    /// When present, the index of the function defined as `start` of the module.
     pub start_index: Option<FunctionIndex>,
 }
 
-/// A function in a WebAssembly module can be either imported, or defined inside it. If it is
-/// defined inside it, then the translation in Cretonne IL is available as well as the mappings
-/// between Cretonne imports and indexes in the function index space.
+/// A function in a WebAssembly module can be either imported, or defined inside it.
 #[derive(Clone)]
 pub enum FunctionTranslation {
+    /// A function defined inside the WebAssembly module.
     Code {
+        /// The translation in Cretonne IL.
         il: Function,
+        /// The mappings between Cretonne imports and indexes in the function index space.
         imports: ImportMappings,
     },
+    /// An imported function.
     Import(),
 }
 
@@ -42,6 +45,7 @@ pub struct ImportMappings {
 }
 
 impl ImportMappings {
+    /// Create a new empty `ImportMappings`.
     pub fn new() -> ImportMappings {
         ImportMappings {
             functions: HashMap::new(),
diff --git a/lib/wasm/src/translation_utils.rs b/lib/wasm/src/translation_utils.rs
index 04921d254f..609b4a3dfc 100644
--- a/lib/wasm/src/translation_utils.rs
+++ b/lib/wasm/src/translation_utils.rs
@@ -32,27 +32,39 @@ pub enum Import {
 /// WebAssembly global.
 #[derive(Debug,Clone,Copy)]
 pub struct Global {
+    /// The type of the value stored in the global.
     pub ty: cretonne::ir::Type,
+    /// A flag indicating whether the value may change at runtime.
     pub mutability: bool,
+    /// The source of the initial value.
     pub initializer: GlobalInit,
 }
 
 /// Globals are initialized via the four `const` operators or by referring to another import.
 #[derive(Debug,Clone,Copy)]
 pub enum GlobalInit {
+    /// An `i32.const`.
     I32Const(i32),
+    /// An `i64.const`.
     I64Const(i64),
+    /// An `f32.const`.
     F32Const(u32),
+    /// An `f64.const`.
     F64Const(u64),
-    Import(),
+    /// A `get_global` of another global.
     GlobalRef(GlobalIndex),
+    ///< The global is imported from, and thus initialized by, a different module.
+    Import(),
 }
 
 /// WebAssembly table.
 #[derive(Debug,Clone,Copy)]
 pub struct Table {
+    /// The type of data stored in elements of the table.
     pub ty: TableElementType,
+    /// The minimum number of elements in the table.
     pub size: usize,
+    /// The maximum number of elements in the table.
     pub maximum: Option<usize>,
 }
 
@@ -66,7 +78,9 @@ pub enum TableElementType {
 /// WebAssembly linear memory.
 #[derive(Debug,Clone,Copy)]
 pub struct Memory {
+    /// The minimum number of pages in the memory.
     pub pages_count: usize,
+    /// The maximum number of pages in the memory.
     pub maximum: Option<usize>,
 }