Require documentation on cretonne public items.

lib/cretonne/src/ir/condcodes.rs

@@ -29,15 +29,25 @@ pub trait CondCode: Copy {
 /// difference.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum IntCC {
+    /// `==`.
     Equal,
+    /// `!=`.
     NotEqual,
+    /// Signed `<`.
     SignedLessThan,
+    /// Signed `>=`.
     SignedGreaterThanOrEqual,
+    /// Signed `>`.
     SignedGreaterThan,
+    /// Signed `<=`.
     SignedLessThanOrEqual,
+    /// Unsigned `<`.
     UnsignedLessThan,
+    /// Unsigned `>=`.
     UnsignedGreaterThanOrEqual,
+    /// Unsigned `>`.
     UnsignedGreaterThan,
+    /// Unsigned `<=`.
     UnsignedLessThanOrEqual,
 }
 
@@ -131,24 +141,38 @@ impl FromStr for IntCC {
 /// except the impossible `!UN & !EQ & !LT & !GT` and the always true `UN | EQ | LT | GT`.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum FloatCC {
-    Ordered, // EQ | LT | GT
-    Unordered, // UN
+    /// EQ | LT | GT
+    Ordered,
+    /// UN
+    Unordered,
 
-    Equal, // EQ
-    // The C '!=' operator is the inverse of '==': NotEqual.
-    NotEqual, // UN | LT | GT
-    OrderedNotEqual, // LT | GT
-    UnorderedOrEqual, // UN | EQ
+    /// EQ
+    Equal,
+    /// The C '!=' operator is the inverse of '==': `NotEqual`.
+    /// UN | LT | GT
+    NotEqual,
+    /// LT | GT
+    OrderedNotEqual,
+    /// UN | EQ
+    UnorderedOrEqual,
 
-    LessThan, // LT
-    LessThanOrEqual, // LT | EQ
-    GreaterThan, // GT
-    GreaterThanOrEqual, // GT | EQ
+    /// LT
+    LessThan,
+    /// LT | EQ
+    LessThanOrEqual,
+    /// GT
+    GreaterThan,
+    /// GT | EQ
+    GreaterThanOrEqual,
 
-    UnorderedOrLessThan, // UN | LT
-    UnorderedOrLessThanOrEqual, // UN | LT | EQ
-    UnorderedOrGreaterThan, // UN | GT
-    UnorderedOrGreaterThanOrEqual, // UN | GT | EQ
+    /// UN | LT
+    UnorderedOrLessThan,
+    /// UN | LT | EQ
+    UnorderedOrLessThanOrEqual,
+    /// UN | GT
+    UnorderedOrGreaterThan,
+    /// UN | GT | EQ
+    UnorderedOrGreaterThanOrEqual,
 }
 
 impl CondCode for FloatCC {

lib/cretonne/src/ir/entities.rs

@@ -98,16 +98,16 @@ impl Default for Inst {
 #[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
 pub struct Value(u32);
 
-// Value references can either reference an instruction directly, or they can refer to the extended
-// value table.
+/// Value references can either reference an instruction directly, or they can refer to the
+/// extended value table.
 pub enum ExpandedValue {
-    // This is the first value produced by the referenced instruction.
+    /// This is the first value produced by the referenced instruction.
     Direct(Inst),
 
-    // This value is described in the extended value table.
+    /// This value is described in the extended value table.
     Table(usize),
 
-    // This is NO_VALUE.
+    /// This is NO_VALUE.
     None,
 }
 
@@ -135,19 +135,23 @@ impl Value {
             None
         }
     }
+    /// Create a `Direct` value corresponding to the first value produced by `i`.
     pub fn new_direct(i: Inst) -> Value {
         let encoding = i.index() * 2;
         assert!(encoding < u32::MAX as usize);
         Value(encoding as u32)
     }
 
+    /// Create a `Table` value referring to entry `i` in the `DataFlowGraph.extended_values` table.
+    /// This constructor should not be used directly. Use the public `DataFlowGraph` methods to
+    /// manipulate values.
     pub fn new_table(index: usize) -> Value {
         let encoding = index * 2 + 1;
         assert!(encoding < u32::MAX as usize);
         Value(encoding as u32)
     }
 
-    // Expand the internal representation into something useful.
+    /// Expand the internal representation into something useful.
     pub fn expand(&self) -> ExpandedValue {
         use self::ExpandedValue::*;
         if *self == NO_VALUE {
@@ -312,12 +316,19 @@ impl Default for SigRef {
 pub enum AnyEntity {
     /// The whole function.
     Function,
+    /// An extended basic block.
     Ebb(Ebb),
+    /// An instruction.
     Inst(Inst),
+    /// An SSA value.
     Value(Value),
+    /// A stack slot.
     StackSlot(StackSlot),
+    /// A jump table.
     JumpTable(JumpTable),
+    /// An external function.
     FuncRef(FuncRef),
+    /// A function call signature.
     SigRef(SigRef),
 }
 

lib/cretonne/src/ir/extfunc.rs

@@ -14,11 +14,14 @@ use ir::{Type, FunctionName, SigRef};
 /// details that are needed to call a function correctly.
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub struct Signature {
+    /// Types of the arguments passed to the function.
     pub argument_types: Vec<ArgumentType>,
+    /// Types returned from the function.
     pub return_types: Vec<ArgumentType>,
 }
 
 impl Signature {
+    /// Create a new blank signature.
     pub fn new() -> Signature {
         Signature {
             argument_types: Vec::new(),
@@ -59,13 +62,16 @@ impl Display for Signature {
 /// how the argument is passed.
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 pub struct ArgumentType {
+    /// Type of the argument value.
     pub value_type: Type,
+    /// Method for extending argument to a full register.
     pub extension: ArgumentExtension,
     /// Place this argument in a register if possible.
     pub inreg: bool,
 }
 
 impl ArgumentType {
+    /// Create an argument type with default flags.
     pub fn new(vt: Type) -> ArgumentType {
         ArgumentType {
             value_type: vt,
@@ -109,7 +115,9 @@ pub enum ArgumentExtension {
 /// Information about a function that can be called directly with a direct `call` instruction.
 #[derive(Clone, Debug)]
 pub struct ExtFuncData {
+    /// Name of the external function.
     pub name: FunctionName,
+    /// Call signature of function.
     pub signature: SigRef,
 }
 

lib/cretonne/src/ir/funcname.rs

@@ -14,6 +14,7 @@ use std::ascii::AsciiExt;
 pub struct FunctionName(String);
 
 impl FunctionName {
+    /// Create new function name equal to `s`.
     pub fn new<S: Into<String>>(s: S) -> FunctionName {
         FunctionName(s.into())
     }

lib/cretonne/src/ir/immediates.rs

@@ -17,6 +17,7 @@ use std::str::FromStr;
 pub struct Imm64(i64);
 
 impl Imm64 {
+    /// Create a new `Imm64` representing the signed number `x`.
     pub fn new(x: i64) -> Imm64 {
         Imm64(x)
     }
@@ -374,6 +375,7 @@ fn parse_float(s: &str, w: u8, t: u8) -> Result<u64, &'static str> {
 }
 
 impl Ieee32 {
+    /// Create a new `Ieee32` representing the number `x`.
     pub fn new(x: f32) -> Ieee32 {
         Ieee32(x)
     }
@@ -403,6 +405,7 @@ impl FromStr for Ieee32 {
 }
 
 impl Ieee64 {
+    /// Create a new `Ieee64` representing the number `x`.
     pub fn new(x: f64) -> Ieee64 {
         Ieee64(x)
     }

lib/cretonne/src/ir/instructions.rs

@@ -93,6 +93,7 @@ impl FromStr for Opcode {
 /// 16 bytes on 64-bit architectures. If more space is needed to represent an instruction, use a
 /// `Box<AuxData>` to store the additional information out of line.
 #[derive(Clone, Debug)]
+#[allow(missing_docs)]
 pub enum InstructionData {
     Nullary { opcode: Opcode, ty: Type },
     Unary {
@@ -226,14 +227,17 @@ pub enum InstructionData {
 pub struct VariableArgs(Vec<Value>);
 
 impl VariableArgs {
+    /// Create an empty argument list.
     pub fn new() -> VariableArgs {
         VariableArgs(Vec::new())
     }
 
+    /// Add an argument to the end.
     pub fn push(&mut self, v: Value) {
         self.0.push(v)
     }
 
+    /// Check if the list is empty.
     pub fn is_empty(&self) -> bool {
         self.0.is_empty()
     }
@@ -276,6 +280,7 @@ impl Default for VariableArgs {
 /// Payload data for `vconst`.
 #[derive(Clone, Debug)]
 pub struct UnaryImmVectorData {
+    /// Raw vector data.
     pub imm: ImmVector,
 }
 
@@ -292,6 +297,7 @@ impl Display for UnaryImmVectorData {
 /// Payload data for ternary instructions with multiple results, such as `iadd_carry`.
 #[derive(Clone, Debug)]
 pub struct TernaryOverflowData {
+    /// Value arguments.
     pub args: [Value; 3],
 }
 
@@ -305,7 +311,9 @@ impl Display for TernaryOverflowData {
 /// in the allowed InstructionData size.
 #[derive(Clone, Debug)]
 pub struct JumpData {
+    /// Jump destination EBB.
     pub destination: Ebb,
+    /// Arguments passed to destination EBB.
     pub varargs: VariableArgs,
 }
 
@@ -323,8 +331,11 @@ impl Display for JumpData {
 /// in the allowed InstructionData size.
 #[derive(Clone, Debug)]
 pub struct BranchData {
+    /// Value argument controlling the branch.
     pub arg: Value,
+    /// Branch destination EBB.
     pub destination: Ebb,
+    /// Arguments passed to destination EBB.
     pub varargs: VariableArgs,
 }
 
@@ -353,6 +364,8 @@ pub struct CallData {
 pub struct IndirectCallData {
     /// Callee function.
     pub arg: Value,
+
+    /// Signature of the callee function.
     pub sig_ref: SigRef,
 
     /// Dynamically sized array containing call argument values.
@@ -362,7 +375,7 @@ pub struct IndirectCallData {
 /// Payload of a return instruction.
 #[derive(Clone, Debug)]
 pub struct ReturnData {
-    // Dynamically sized array containing return values.
+    /// Dynamically sized array containing return values.
     pub varargs: VariableArgs,
 }