Update some documentation for yuidoc

Much work is required to get the API documentation into a
good state. Much of the codebase needs documenting, or
correcting to make it yuidoc compliant