Auto merge of #297 - waywardmonkeys:macro-docs, r=jdm

Begin documenting core-foundation macros.

I started doing this after talking through some issues with @raphlinus. Clearly more to do, but would like to get this in sooner rather than later.

<!-- Reviewable:start -->
---
This change is [<img src="https://reviewable.io/review_button.svg" height="34" align="absmiddle" alt="Reviewable"/>](https://reviewable.io/reviews/servo/core-foundation-rs/297)
<!-- Reviewable:end -->

core-foundation/src/base.rs

@@ -111,6 +111,9 @@ impl CFType {
 }
 
 impl fmt::Debug for CFType {
+   /// Formats the value using [`CFCopyDescription`].
+   ///
+   /// [`CFCopyDescription`]: https://developer.apple.com/documentation/corefoundation/1521252-cfcopydescription?language=objc
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         let desc = unsafe {
             CFString::wrap_under_create_rule(CFCopyDescription(self.0))
@@ -154,6 +157,10 @@ impl CFAllocator {
 /// All Core Foundation types implement this trait. The associated type `Ref` specifies the
 /// associated Core Foundation type: e.g. for `CFType` this is `CFTypeRef`; for `CFArray` this is
 /// `CFArrayRef`.
+///
+/// Most structs that implement this trait will do so via the [`impl_TCFType`] macro.
+///
+/// [`impl_TCFType`]: ../macro.impl_TCFType.html
 pub trait TCFType {
     /// The reference type wrapped inside this type.
     type Ref: TCFTypeRef;

core-foundation/src/lib.rs

@@ -6,8 +6,15 @@
 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
+
 #![allow(non_snake_case)]
 
+//! This crate provides wrappers around the underlying CoreFoundation
+//! types and functions that are available on Apple's operating systems.
+//!
+//! It also provides a framework for other crates to use when wrapping
+//! other frameworks that use the CoreFoundation framework.
+
 extern crate core_foundation_sys;
 extern crate libc;
 
@@ -18,6 +25,34 @@ use base::TCFType;
 
 pub unsafe trait ConcreteCFType: TCFType {}
 
+/// Declare a Rust type that wraps an underlying CoreFoundation type.
+///
+/// This will provide an implementation of `Drop` using [`CFRelease`].
+/// The type must have an implementation of the [`TCFType`] trait, usually
+/// provided using the [`impl_TCFType`] macro.
+///
+/// ```
+/// #[macro_use] extern crate core_foundation;
+/// // Make sure that the `TCFType` trait is in scope.
+/// use core_foundation::base::{CFTypeID, TCFType};
+///
+/// extern "C" {
+///     // We need a function that returns the `CFTypeID`.
+///     pub fn ShrubberyGetTypeID() -> CFTypeID;
+/// }
+///
+/// pub struct __Shrubbery {}
+/// // The ref type must be a pointer to the underlying struct.
+/// pub type ShrubberyRef = *const __Shrubbery;
+///
+/// declare_TCFType!(Shrubbery, ShrubberyRef);
+/// impl_TCFType!(Shrubbery, ShrubberyRef, ShrubberyGetTypeID);
+/// # fn main() {}
+/// ```
+///
+/// [`CFRelease`]: https://developer.apple.com/documentation/corefoundation/1521153-cfrelease
+/// [`TCFType`]: base/trait.TCFType.html
+/// [`impl_TCFType`]: macro.impl_TCFType.html
 #[macro_export]
 macro_rules! declare_TCFType {
     (
@@ -35,6 +70,13 @@ macro_rules! declare_TCFType {
     }
 }
 
+/// Provide an implementation of the [`TCFType`] trait for the Rust
+/// wrapper type around an underlying CoreFoundation type.
+///
+/// See [`declare_TCFType`] for details.
+///
+/// [`declare_TCFType`]: macro.declare_TCFType.html
+/// [`TCFType`]: base/trait.TCFType.html
 #[macro_export]
 macro_rules! impl_TCFType {
     ($ty:ident, $ty_ref:ident, $ty_id:ident) => {
@@ -122,6 +164,18 @@ macro_rules! impl_TCFType {
 }
 
 
+/// Implement `std::fmt::Debug` for the given type.
+///
+/// This will invoke the implementation of `Debug` for [`CFType`]
+/// which invokes [`CFCopyDescription`].
+///
+/// The type must have an implementation of the [`TCFType`] trait, usually
+/// provided using the [`impl_TCFType`] macro.
+///
+/// [`CFType`]: base/struct.CFType.html#impl-Debug
+/// [`CFCopyDescription`]: https://developer.apple.com/documentation/corefoundation/1521252-cfcopydescription?language=objc
+/// [`TCFType`]: base/trait.TCFType.html
+/// [`impl_TCFType`]: macro.impl_TCFType.html
 #[macro_export]
 macro_rules! impl_CFTypeDescription {
     ($ty:ident) => {