Clarify documentation

Author: TomBebbington

Cargo.lock

@@ -7,7 +7,7 @@ use util;
 pub struct BasicBlock;
 native_ref!(&BasicBlock = LLVMBasicBlockRef);
 impl BasicBlock {
-    /// Return the enclosing method, or `None` if it is non-existant.
+    /// Return the enclosing method, or `None` if it is not attached to a method.
     pub fn get_parent(&self) -> Option<&Value> {
         unsafe { util::ptr_to_null(core::LLVMGetBasicBlockParent(self.into())) }
     }
@@ -26,7 +26,7 @@ impl BasicBlock {
     /// Delete this basic block.
     ///
     /// This is unsafe because there should be no other reference to this, but
-    /// this can't be guranteed.
+    /// this can't be guranteed using Rust semantics.
     pub unsafe fn delete(&self) {
         core::LLVMDeleteBasicBlock(self.into())
     }

src/block.rs

@@ -114,7 +114,7 @@ impl Builder {
     pub fn build_bit_cast(&self, value: &Value, dest: &Type) -> &Value {
         unsafe { core::LLVMBuildBitCast(self.into(), value.into(), dest.into(), NULL_NAME.as_ptr()).into() }
     }
-    /// Build an instruction that inserts a value into an aggregate type.
+    /// Build an instruction that inserts a value into an aggregate data value.
     pub fn build_insert_value(&self, agg: &Value, elem: &Value, index: usize) -> &Value {
         unsafe { core::LLVMBuildInsertValue(self.into(), agg.into(), elem.into(), index as c_uint, NULL_NAME.as_ptr()).into() }
     }
@@ -145,7 +145,7 @@ impl Builder {
     bin_op!{build_ashr, LLVMBuildAShr}
     bin_op!{build_and, LLVMBuildAnd}
     bin_op!{build_or, LLVMBuildOr}
-    /// Build an instruction to compare two values with the predicate
+    /// Build an instruction to compare two values with the predicate given.
     pub fn build_cmp(&self, a: &Value, b: &Value, pred: Predicate) -> &Value {
         let (at, bt) = (a.get_type(), b.get_type());
         assert_eq!(at, bt);

src/builder.rs

@@ -8,9 +8,9 @@ use ty::{StructType, Type};
 use std::mem;
 use std::ffi::CStr;
 
-/// Implemented for any type that can be represented as a constant in IR.
+/// A type that can be represented as a constant in LLVM IR.
 pub trait Compile<'a> {
-    /// Compile this value in the context given.
+    /// Compile this value into a constant in the context given.
     fn compile(self, context: &'a Context) -> &'a Value;
     /// Get the type descriptor for this type in the context given.
     fn get_type(context: &'a Context) -> &'a Type;

src/compile.rs

@@ -2,11 +2,11 @@ use ffi::prelude::LLVMContextRef;
 use ffi::{core, LLVMContext};
 use cbox::CBox;
 
-/// Contains all the LLVM entities such as modules.
+/// Contains all the LLVM entities - mainly modules.
 ///
 /// Every single entity attached to it has its lifetime to enforce the
-/// rule that things from different contexts cannot interact and to keep
-/// their pointer safety intact.
+/// rule that things from different contexts cannot interact and to
+/// preserve pointer safety.
 pub struct Context;
 native_ref!(&Context = LLVMContextRef);
 impl Context {
@@ -17,7 +17,7 @@ impl Context {
     pub unsafe fn get_global() -> &'static Context {
         core::LLVMGetGlobalContext().into()
     }
-    /// Create a new context, owned by the block that calls it.
+    /// Create a new context, which is owned by the callee block.
     pub fn new() -> CBox<Self> {
         CBox::new(unsafe { core::LLVMContextCreate() })
     }

src/context.rs

@@ -18,7 +18,7 @@ use value::{Function, Value};
 ///
 /// This is designed to support both interpreter and just-in-time (JIT) compiler implementations.
 pub trait ExecutionEngine<'a, 'b:'a> where LLVMExecutionEngineRef:From<&'b Self> {
-    /// The options given to this upon creation.
+    /// The options given to the engine upon creation.
     type Options : Copy;
     /// Create a new execution engine with the given `Module` and options, or return a
     /// description of the error.

src/engine.rs

@@ -1,5 +1,8 @@
-//! This library provides wrappers for LLVM that are (mostly) memory-safe and follow
+//! This library provides wrappers for LLVM that are memory-safe and follow
 //! Rust idioms.
+//!
+//! The original LLVM reference is available [here](http://llvm.org/doxygen/)
+//! but take note that this isn't as thorough as this documentation.
 
 extern crate llvm_sys as ffi;
 extern crate libc;

src/lib.rs

@@ -20,7 +20,7 @@ use value::{Function, Value};
 use ty::Type;
 use util;
 
-/// Represents a single translation unit of code.
+/// Represents a single compilation unit of code.
 ///
 /// This is attached to the lifetime of the context that constructs it, but is owned by the `CSemiBox`.
 pub struct Module;
@@ -91,15 +91,15 @@ impl Module {
         let c_name = CString::new(name).unwrap();
         unsafe { core::LLVMAddFunction(self.into(), c_name.as_ptr(), sig.into()) }.into()
     }
-    /// Returns the function with the name given if it exists.
+    /// Returns the function with the name given, or `None` if no function with that name exists.
     pub fn get_function<'a>(&'a self, name: &str) -> Option<&'a Function> {
         let c_name = CString::new(name).unwrap();
         unsafe {
             let ty = core::LLVMGetNamedFunction(self.into(), c_name.as_ptr());
             util::ptr_to_null(ty)
         }
     }
-    /// Returns the type with the name given if it exists.
+    /// Returns the type with the name given, or `None`` if no type with that name exists.
     pub fn get_type<'a>(&'a self, name: &str) -> Option<&'a Type> {
         let c_name = CString::new(name).unwrap();
         unsafe {
@@ -113,6 +113,8 @@ impl Module {
     }
 
     /// Optimize this module with the given optimization level and size level.
+    ///
+    /// This runs passes depending on the levels given.
     pub fn optimize(&self, opt_level: usize, size_level: usize) {
         unsafe {
             let builder = builder::LLVMPassManagerBuilderCreate();
@@ -133,13 +135,14 @@ impl Module {
         }
     }
 
-    /// Set the target data of this module
+    /// Set the target data of this module to the target data string given.
     pub fn set_target(&self, target: &str) {
         let c_target = CString::new(target).unwrap();
         unsafe { core::LLVMSetTarget(self.into(), c_target.as_ptr()) }
     }
 
-    /// Verify that the module is safe to run.
+    /// Verify that the module is safe to run, returning a string detailing the error
+    /// when an error occurs.
     pub fn verify(&self) -> Result<(), CBox<str>> {
         unsafe {
             let mut error = mem::uninitialized();
@@ -171,7 +174,9 @@ impl Module {
             .map(|_| ())
     }
 
-    /// Link a module into this module
+    /// Link a module into this module, returning an error string if an error occurs.
+    ///
+    /// This *does not* destroy the source module.
     pub fn link(&self, src: &Module) -> Result<(), CBox<str>> {
         unsafe {
             let dest = self.into();
@@ -185,7 +190,9 @@ impl Module {
         }
     }
 
-    /// Link a module into this module
+    /// Link a module into this module, returning an error string if an error occurs.
+    ///
+    /// This *does* destroy the source module.
     pub fn link_destroy(&self, src: CSemiBox<Module>) -> Result<(), CBox<str>> {
         unsafe {
             let dest = self.into();

src/module.rs

@@ -8,13 +8,13 @@ use std::mem;
 use buffer::MemoryBuffer;
 use util;
 
-/// An external object file that has been parsed by LLVLM
+/// An external object file that has been parsed by LLVM.
 pub struct ObjectFile {
     obj: LLVMObjectFileRef
 }
 native_ref!(ObjectFile, obj: LLVMObjectFileRef);
 impl ObjectFile {
-    /// Attempt to parse the object file at the path given
+    /// Parse the object file at the path given, or return an error string if an error occurs.
     pub fn read(path: &str) -> Result<ObjectFile, CBox<str>> {
         let buf = try!(MemoryBuffer::new_from_file(path));
         unsafe {
@@ -26,7 +26,7 @@ impl ObjectFile {
             }
         }
     }
-    /// Iterate through the symbols in this object fil
+    /// Iterate through the symbols in this object file.
     pub fn symbols(&self) -> Symbols {
         Symbols {
             iter: unsafe { object::LLVMGetSymbols(self.obj) },
@@ -61,7 +61,9 @@ impl<'a> Drop for Symbols<'a> {
     }
 }
 pub struct Symbol<'a> {
+    /// The name of this symbol.
     pub name: &'a str,
+    /// The address that this symbol is at.
     pub address: *const c_void,
     pub size: usize
 }
@@ -77,7 +79,7 @@ impl<'a> fmt::Debug for Symbol<'a> {
     }
 }
 impl<'a> Symbol<'a> {
-    /// Get the pointer for this symbol
+    /// Get the pointer for this symbol.
     pub unsafe fn get<T>(self) -> &'a T {
         mem::transmute(self.address)
     }

src/object.rs

@@ -7,16 +7,17 @@ use std::fmt;
 use ty::Type;
 use util;
 
+/// Represents an LLVM Target
 pub struct TargetData;
 native_ref!(&TargetData = LLVMTargetDataRef);
 
 impl TargetData {
-    /// Creates target data from a target layout string.
+    /// Create a target data from a target layout string.
     pub fn new(rep: &str) -> CBox<TargetData> {
         let c_rep = CString::new(rep).unwrap();
         CBox::new(unsafe {
             target::LLVMCreateTargetData(c_rep.as_ptr())
-        }.into())
+        }.Returns truento())
     }
     /// Returns true if the target is big endian.
     pub fn is_big_endian(&self) -> bool {
@@ -47,7 +48,7 @@ impl TargetData {
     pub fn offset_of(&self, struct_ty: &Type, element: usize) -> u64 {
         unsafe { target::LLVMOffsetOfElement(self.into(), struct_ty.into(), element as c_uint) }
     }
-    /// Converts this to a target layout string and returns it.
+    /// Returns the string representation of this target data.
     pub fn as_str(&self) -> CBox<str> {
         unsafe {
             CBox::new(target::LLVMCopyStringRepOfTargetData(self.into()))
@@ -78,15 +79,15 @@ impl Target {
     pub fn get_description(&self) -> &str {
         unsafe { util::to_str(target_machine::LLVMGetTargetDescription(self.into()) as *mut c_char) }
     }
-    /// Returns `true` if this target has an assembly generation backend in LLVM.
+    /// Returns true if this target has an assembly generation backend implemented.
     pub fn has_asm_backend(&self) -> bool {
         unsafe { target_machine::LLVMTargetHasAsmBackend(self.into()) != 0 }
     }
-    /// Returns `true` if this target supports JIT compilation.
+    /// Returns true if this target supports JIT compilation.
     pub fn has_jit(&self) -> bool {
         unsafe { target_machine::LLVMTargetHasJIT(self.into()) != 0 }
     }
-    /// Returns `true` if this target has a target machine.
+    /// Returns true if this target has a target machine.
     pub fn has_target_machine(&self) -> bool {
         unsafe { target_machine::LLVMTargetHasTargetMachine(self.into()) != 0 }
     }