Cleanup token handling code

1. Adds function header documentation to the two token hooks
2. Adds a double check that $object is not empty.
3. Significantly reduces the number of calls to _category_tokens_title_to_id() when unnecessary.
4. Uses check_plain() on the non-raw token values which is standard procedure.
5. Provides pathauto with the array of the path if $options['pathauto'] = TRUE so it can clean up each path segment properly. See #881270: [bookpath], [menupath], [*path] tokens not cleaned: aliases without punctuation removed, lower casing, etc. for more information why this is necessary.
6. Returns the token listing when $type == 'all', which is standard procedure.