Add some documentation and manifest metadata.

Author: alexcrichton

Cargo.toml

@@ -2,6 +2,14 @@
 name = "dlmalloc"
 version = "0.1.0"
 authors = ["Alex Crichton <alex@alexcrichton.com>"]
+license = "MIT/Apache-2.0"
+readme = "README.md"
+repository = "https://github.com/alexcrichton/dlmalloc-rs"
+homepage = "https://github.com/alexcrichton/dlmalloc-rs"
+documentation = "https://docs.rs/dlmalloc"
+description = """
+A Rust port of the dlmalloc allocator
+"""
 
 [lib]
 doctest = false

src/dlmalloc.rs

@@ -109,10 +109,6 @@ fn leftshift_for_tree_index(x: u32) -> u32 {
 }
 
 impl Dlmalloc {
-    pub fn new() -> Dlmalloc {
-        DLMALLOC_INIT
-    }
-
     // TODO: can we get rid of this?
     pub fn malloc_alignment(&self) -> usize {
         mem::size_of::<usize>() * 2

src/global.rs

@@ -7,6 +7,10 @@ use core::alloc::{AllocErr, Alloc};
 
 use Dlmalloc;
 
+/// An instance of a "global allocator" backed by `Dlmalloc`
+///
+/// This API requires the `global` feature is activated, and this type
+/// implements the `GlobalAlloc` trait in the standard library.
 pub struct GlobalDlmalloc;
 
 unsafe impl GlobalAlloc for GlobalDlmalloc {

src/lib.rs

@@ -1,7 +1,21 @@
+//! A Rust port of the `dlmalloc` allocator.
+//!
+//! The `dlmalloc` allocator is described at
+//! http://g.oswego.edu/dl/html/malloc.html and this Rust crate is a straight
+//! port of the C code for the allocator into Rust. The implementation is
+//! wrapped up in a `Dlmalloc` type and has support for Linux, OSX, and Wasm
+//! currently.
+//!
+//! The primary purpose of this crate is that it serves as the default memory
+//! allocator for the `wasm32-unknown-unknown` target in the standard library.
+//! Support for other platforms is largely untested and unused, but is used when
+//! testing this crate.
+
 #![cfg_attr(feature = "allocator-api", feature(allocator_api))]
 #![cfg_attr(target_arch = "wasm32", feature(link_llvm_intrinsics))]
 #![cfg_attr(not(feature = "allocator-api"), allow(dead_code))]
 #![no_std]
+#![deny(missing_docs)]
 
 #[cfg(feature = "allocator-api")]
 use core::alloc::{Alloc, Layout, AllocErr};
@@ -15,8 +29,14 @@ pub use self::global::GlobalDlmalloc;
 mod global;
 mod dlmalloc;
 
+/// An allocator instance
+///
+/// Instances of this type are used to allocate blocks of memory. For best
+/// results only use one of these. Currently doesn't implement `Drop` to release
+/// lingering memory back to the OS. That may happen eventually though!
 pub struct Dlmalloc(dlmalloc::Dlmalloc);
 
+/// Constant initializer for `Dlmalloc` structure.
 pub const DLMALLOC_INIT: Dlmalloc = Dlmalloc(dlmalloc::DLMALLOC_INIT);
 
 #[cfg(target_arch = "wasm32")]
@@ -32,10 +52,18 @@ mod sys;
 mod sys;
 
 impl Dlmalloc {
+    /// Creates a new instance of an allocator, same as `DLMALLOC_INIT`.
     pub fn new() -> Dlmalloc {
-        Dlmalloc(dlmalloc::Dlmalloc::new())
+        DLMALLOC_INIT
     }
 
+    /// Allocates `size` bytes with `align` align.
+    ///
+    /// Returns a null pointer if allocation fails. Returns a valid pointer
+    /// otherwise.
+    ///
+    /// Safety and contracts are largely governed by the `GlobalAlloc::alloc`
+    /// method contracts.
     #[inline]
     pub unsafe fn malloc(&mut self, size: usize, align: usize) -> *mut u8 {
         if align <= self.0.malloc_alignment() {
@@ -45,6 +73,8 @@ impl Dlmalloc {
         }
     }
 
+    /// Same as `malloc`, except if the allocation succeeds it's guaranteed to
+    /// point to `size` bytes of zeros.
     #[inline]
     pub unsafe fn calloc(&mut self, size: usize, align: usize) -> *mut u8 {
         let ptr = self.malloc(size, align);
@@ -54,12 +84,26 @@ impl Dlmalloc {
         ptr
     }
 
+    /// Deallocates a `ptr` with `size` and `align` as the previous request used
+    /// to allocate it.
+    ///
+    /// Safety and contracts are largely governed by the `GlobalAlloc::dealloc`
+    /// method contracts.
     #[inline]
     pub unsafe fn free(&mut self, ptr: *mut u8, size: usize, align: usize) {
         drop((size, align));
         self.0.free(ptr)
     }
 
+    /// Reallocates `ptr`, a previous allocation with `old_size` and
+    /// `old_align`, to have `new_size` and the same alignment as before.
+    ///
+    /// Returns a null pointer if the memory couldn't be reallocated, but `ptr`
+    /// is still valid. Returns a valid pointer and frees `ptr` if the request
+    /// is satisfied.
+    ///
+    /// Safety and contracts are largely governed by the `GlobalAlloc::realloc`
+    /// method contracts.
     #[inline]
     pub unsafe fn realloc(&mut self,
                           ptr: *mut u8,