Refactor (#285)

src/lib.rs

@@ -42,19 +42,31 @@ extern "C" {
 pub struct Allocator;
 
 impl Allocator {
+    /// Locks a collector.
     pub fn lock() {
         unsafe { GC_alloc_lock() }
     }
 
+    /// Unlocks a collector.
     pub fn unlock() {
         unsafe { GC_alloc_unlock() }
     }
 
+    /// Initializes a collector.
+    ///
+    /// # Safety
+    ///
+    /// This function must be called in a main thread.
     pub unsafe fn initialize() {
         GC_init();
         GC_allow_register_threads();
     }
 
+    /// Registers a current thread to a collector.
+    ///
+    /// # Safety
+    ///
+    /// This function must not be called in a main thread.
     pub unsafe fn register_current_thread() -> Result<(), error::Error> {
         let mut base = GcStackBase { mem_base: null() };
 
@@ -67,6 +79,14 @@ impl Allocator {
         Ok(())
     }
 
+    /// Sets a bottom of a stack.
+    ///
+    /// You do not have to call this function in most cases.
+    /// A collector detects the bottom on initialization automatically.
+    ///
+    /// # Safety
+    ///
+    /// The bottom address must be valid.
     pub unsafe fn set_stack_bottom(bottom: *const u8) {
         GC_set_stackbottom(
             null(),
@@ -76,14 +96,25 @@ impl Allocator {
         )
     }
 
+    /// Unregisters a current thread from a collector.
+    ///
+    /// # Safety
+    ///
+    /// The thread must be registered already.
     pub unsafe fn unregister_current_thread() {
         GC_unregister_my_thread()
     }
 
+    /// Runs a garbage collection forcibly.
     pub fn force_collect() {
         unsafe { GC_gcollect() }
     }
 
+    /// Registers a finalizer of an object.
+    ///
+    /// # Safety
+    ///
+    /// The given finalizer must not be null and handle pointers properly.
     pub unsafe fn register_finalizer(
         ptr: *const c_void,
         finalizer: extern "C" fn(*mut c_void, *mut c_void),