Una de las cosas que se hacen es seguir un estándar en los comentarios, que si ya has trabajado con scripts o snippets lo habrás visto.
El estándar que se sigue para los comentarios es el de
PEAR. Si quieres saber más, puedes leer un artículo que escribí sobre ello hace poco en
http://rubenmartin.me/2012/phpdoc-el...e-comentarios/.
Después se suele procesar con
PHPdoc para crear una API, e incluso algunos IDEs saben leer esos comentarios.