From f19456640cce8d370ce181c5a433db6942293ae3 Mon Sep 17 00:00:00 2001
From: Andrew Brown <andrew.brown@intel.com>
Date: Wed, 30 Oct 2019 17:54:04 -0700
Subject: [PATCH] Add documentation for top-level items in
 cranelift-codegen/meta

---
 cranelift/codegen/meta/src/cdsl/mod.rs      | 1 +
 cranelift/codegen/meta/src/default_map.rs   | 1 +
 cranelift/codegen/meta/src/error.rs         | 1 +
 cranelift/codegen/meta/src/gen_inst.rs      | 1 +
 cranelift/codegen/meta/src/gen_legalizer.rs | 1 +
 cranelift/codegen/meta/src/gen_registers.rs | 1 +
 cranelift/codegen/meta/src/gen_settings.rs  | 1 +
 cranelift/codegen/meta/src/isa/mod.rs       | 1 +
 cranelift/codegen/meta/src/lib.rs           | 3 +++
 cranelift/codegen/meta/src/unique_table.rs  | 1 +
 10 files changed, 12 insertions(+)

diff --git a/cranelift/codegen/meta/src/cdsl/mod.rs b/cranelift/codegen/meta/src/cdsl/mod.rs
index 370b442ae4..698b64dff3 100644
--- a/cranelift/codegen/meta/src/cdsl/mod.rs
+++ b/cranelift/codegen/meta/src/cdsl/mod.rs
@@ -39,6 +39,7 @@ macro_rules! predicate {
     };
 }
 
+/// A macro that joins boolean settings into a list (e.g. `preset!(feature_a && feature_b)`).
 #[macro_export]
 macro_rules! preset {
     () => {
diff --git a/cranelift/codegen/meta/src/default_map.rs b/cranelift/codegen/meta/src/default_map.rs
index 951a9b2491..3a2be05dac 100644
--- a/cranelift/codegen/meta/src/default_map.rs
+++ b/cranelift/codegen/meta/src/default_map.rs
@@ -1,3 +1,4 @@
+//! Trait for extending `HashMap` with `get_or_default`.
 use std::collections::HashMap;
 use std::hash::Hash;
 
diff --git a/cranelift/codegen/meta/src/error.rs b/cranelift/codegen/meta/src/error.rs
index 316e69bbc5..4cbf3d8285 100644
--- a/cranelift/codegen/meta/src/error.rs
+++ b/cranelift/codegen/meta/src/error.rs
@@ -1,3 +1,4 @@
+//! Error returned during meta code-generation.
 use std::fmt;
 use std::io;
 
diff --git a/cranelift/codegen/meta/src/gen_inst.rs b/cranelift/codegen/meta/src/gen_inst.rs
index 7904b1ef28..ffadd22d57 100644
--- a/cranelift/codegen/meta/src/gen_inst.rs
+++ b/cranelift/codegen/meta/src/gen_inst.rs
@@ -1,3 +1,4 @@
+//! Generate instruction data (including opcodes, formats, builders, etc.).
 use std::fmt;
 
 use cranelift_codegen_shared::constant_hash;
diff --git a/cranelift/codegen/meta/src/gen_legalizer.rs b/cranelift/codegen/meta/src/gen_legalizer.rs
index b73b67b754..ede525e8bc 100644
--- a/cranelift/codegen/meta/src/gen_legalizer.rs
+++ b/cranelift/codegen/meta/src/gen_legalizer.rs
@@ -1,3 +1,4 @@
+//! Generate transformations to legalize instructions without encodings.
 use crate::cdsl::ast::{Def, DefPool, Expr, VarPool};
 use crate::cdsl::isa::TargetIsa;
 use crate::cdsl::operands::Operand;
diff --git a/cranelift/codegen/meta/src/gen_registers.rs b/cranelift/codegen/meta/src/gen_registers.rs
index df34a20899..fbb61beb37 100644
--- a/cranelift/codegen/meta/src/gen_registers.rs
+++ b/cranelift/codegen/meta/src/gen_registers.rs
@@ -1,3 +1,4 @@
+//! Generate the ISA-specific registers.
 use crate::cdsl::isa::TargetIsa;
 use crate::cdsl::regs::{RegBank, RegClass};
 use crate::error;
diff --git a/cranelift/codegen/meta/src/gen_settings.rs b/cranelift/codegen/meta/src/gen_settings.rs
index a40afbdf4a..2ed5941b80 100644
--- a/cranelift/codegen/meta/src/gen_settings.rs
+++ b/cranelift/codegen/meta/src/gen_settings.rs
@@ -1,3 +1,4 @@
+//! Generate the ISA-specific settings.
 use std::collections::HashMap;
 
 use cranelift_codegen_shared::constant_hash::{generate_table, simple_hash};
diff --git a/cranelift/codegen/meta/src/isa/mod.rs b/cranelift/codegen/meta/src/isa/mod.rs
index 45b68e7c45..39cd913300 100644
--- a/cranelift/codegen/meta/src/isa/mod.rs
+++ b/cranelift/codegen/meta/src/isa/mod.rs
@@ -1,3 +1,4 @@
+//! Define supported ISAs; includes ISA-specific instructions, encodings, registers, settings, etc.
 use crate::cdsl::isa::TargetIsa;
 use crate::shared::Definitions as SharedDefinitions;
 use std::fmt;
diff --git a/cranelift/codegen/meta/src/lib.rs b/cranelift/codegen/meta/src/lib.rs
index 56417002c7..796e2a110d 100644
--- a/cranelift/codegen/meta/src/lib.rs
+++ b/cranelift/codegen/meta/src/lib.rs
@@ -1,3 +1,5 @@
+//! This crate generates Rust sources for use by
+//! [`cranelift_codegen`](../cranelift_codegen/index.html).
 #[macro_use]
 mod cdsl;
 mod srcgen;
@@ -17,6 +19,7 @@ mod default_map;
 mod shared;
 mod unique_table;
 
+/// Generate an ISA from an architecture string (e.g. "x86_64").
 pub fn isa_from_arch(arch: &str) -> Result<isa::Isa, String> {
     isa::Isa::from_arch(arch).ok_or_else(|| format!("no supported isa found for arch `{}`", arch))
 }
diff --git a/cranelift/codegen/meta/src/unique_table.rs b/cranelift/codegen/meta/src/unique_table.rs
index 949aa6b9d3..65ef7e8b4a 100644
--- a/cranelift/codegen/meta/src/unique_table.rs
+++ b/cranelift/codegen/meta/src/unique_table.rs
@@ -1,3 +1,4 @@
+//! An index-accessed table implementation that avoids duplicate entries.
 use std::collections::HashMap;
 use std::hash::Hash;
 use std::slice;