Existem diversas ferramentas na web para gerar a documentação de código baseada em comentários internos ao código.
Um exemplo é o Doxygen, que é capaz de documentar C++, C, Java, Objective-C, Python, IDL (Corba e Microsoft), Fortran, VHDL, PHP, C#, e até certo ponto D.
O importante não é usar uma ferramenta que extraia os comentários do seu código fonte e gere uma documentação bonitinha em HTML. Claro, isso é um atrativo, mas importante mesmo é que o código seja consistente, que os comentários dentro do código sejam razoavelmente descritivos em direcionar o programador e que a formatação do código seja sempre a mesma. Tal feito não é alcançado pela ferramenta que seu time usa para documentar (como Doxygen ou PHPDocumentor), mas sim através da imposição de um Manual de Estilo.
Cada programador tem uma forma de programar, em função de suas características pessoais. Mas na hora de programar comercialmente é importante que todos os membros do time, tanto do presente como do futuro, consigam compreender o código por completo para reutilização do mesmo. E é aí que o Manual de Estilo entra para fazer com que todos escrevam de forma similar.
Um Manual de Estilo deve ser imposto. Claro que em sua implantação sugestões podem (e devem) ser ouvidas, mas todos os envolvidos no projeto precisam segui-lo à risca. Aqui está uma sugestão de peso, o manual de estilo da Bell Labs para a linguagem C, última revisão de Junho de 1990. Seguindo este modelo, é possível criar um manual de estilo que se encaixe à sua empresa. Hoje, talvez pela popularidade de outros como PHPDocumentor e Doxygen, não se deve descartar a possibilidade de utilizar elementos destes dois últimos no seu manual.
