Documentation generator templates which split the comments and the code help with the scope problem of solution 1. E.g.:

http://reload.github.io/phing-drupal-template/

The trade off being that the vertical spacing of the code is now inconsistent.