Improve code docs for drush_get_arguments()

The drush_get_arguments() 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 a @return directive.
2. In my opinion, the explanatory text is more confusing than it needs to be. I think we can simplify it and add an @see directive for more details.

Patch to follow.