Expand rc module docs

Author: SSheldon

src/lib.rs

@@ -20,6 +20,11 @@ let _: () = msg_send![obj, release];
 # }
 ```
 
+# Reference counting
+
+Utilities for reference counting Objective-C objects are provided in the
+[`rc`](rc/index.html) module.
+
 # Declaring classes
 
 Objective-C classes can even be declared from Rust using the functionality of

src/rc/autorelease.rs

@@ -20,8 +20,9 @@ impl Drop for AutoReleaseHelper {
 
 /**
 Execute `f` in the context of a new autorelease pool. The pool is drained
-after the execution of `f` completes. This corresponds to @autoreleasepool blocks
-in Objective-c and Swift.
+after the execution of `f` completes.
+
+This corresponds to `@autoreleasepool` blocks in Objective-C and Swift.
 */
 pub fn autoreleasepool<F: FnOnce()>(f: F) {
     let _context = unsafe { AutoReleaseHelper::new() };

src/rc/mod.rs

@@ -1,12 +1,43 @@
 /*!
-Utilities for reference-counting Objective-C objects.
+Utilities for reference counting Objective-C objects.
 
-These utilities provide ARC-like semantics in Rust. They are not intended to
-provide a fully safe interface, but can be useful when writing higher-level
-Rust wrappers for Objective-C code.
+The utilities of the `rc` module provide ARC-like semantics for working with
+Objective-C's reference counted objects in Rust.
+A `StrongPtr` retains an object and releases the object when dropped.
+A `WeakPtr` will not retain the object, but can be upgraded to a `StrongPtr`
+and safely fails if the object has been deallocated.
+
+These utilities are not intended to provide a fully safe interface, but can be
+useful when writing higher-level Rust wrappers for Objective-C code.
 
 For more information on Objective-C's reference counting, see Apple's documentation:
 <https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/MemoryMgmt.html>
+
+# Example
+
+``` no_run
+# #[macro_use] extern crate objc;
+# use objc::rc::{autoreleasepool, StrongPtr};
+# fn main() {
+// StrongPtr will release the object when dropped
+let obj = unsafe {
+    StrongPtr::new(msg_send![class!(NSObject), new])
+};
+
+// Cloning retains the object an additional time
+let cloned = obj.clone();
+autoreleasepool(|| {
+    // Autorelease consumes the StrongPtr, but won't
+    // actually release until the end of an autoreleasepool
+    cloned.autorelease();
+});
+
+// Weak references won't retain the object
+let weak = obj.weak();
+drop(obj);
+assert!(weak.load().is_null());
+# }
+```
 */
 
 mod strong;