Improve the migration docuemtnation

Move the main explanation of stuff from the documentation block for the
typedef to the doc blocks for the methods and (hopefully) improve the
wording a bit. While this results in most of the documentation being
duplicated, appledoc doesn't actually document typedefs so it didn't
show up in the generated HTML at all previously.