Depende si tu código es un script comun con funciones, o si utilizás orientación a objetos, pero en general lo importante es:
- documentar funciones o clases: para que sirven, que argumentos reciben y que valores retornan.
- documentar algun codigo que sea "confuso".
Lo que NO CONVIENE documentar es el código propiamente dicho. ej:
// sirve para xxxxx
if (!isset($_POST['valor']));
porque se supone que el que lee el codigo ya es programador y sabe para que sirve.
La idea es principalmente documentar funciones y clases ( que argumentos reciben, que valor retornan, como se utilizan, como se instancian, etc)
Podés utilizar
http://www.phpdoc.org/ , hay un standard para eso