Documentation updates

Found a new warning flag that catches bad documentation...

Also reformatted to better support the discussion segment on Cocoadocs.org.