Improve code docs for drush_invoke()

The drush_invoke() code comments have several issues that need fixed to make it clear and precise, to display properly on the API site, and to conform to Drupal's Doxygen and comment formatting conventions. Most importantly...

1. It's missing @param and @return directives.
2. The @see directive is malformed.
3. Function references are missing parentheses and so don't get hyperlinked on the API site.
4. Comments don't always wrap at 80 characters.
5. Inline comments don't always terminate with punctuation.
6. There are a few small typos.

Patch to follow.