Eu não conheço outros ambientes, mas quando se trata de projetos PHP grandes (geralmente de código aberto) que outras pessoas escreveram, o phpXRef é um salva-vidas absoluto (especialmente se o documento for colocado online e o Google puder indexá-lo).
Mesmo um projeto mal comentado pode pelo menos me ajudar a rastrear onde as coisas foram definidas e onde são usadas (por exemplo, ao refatorar).
Quando bem comentadas, as páginas resultantes se aproximam de uma Bíblia perfeita para a base de código (para meus usos de qualquer maneira).
Além disso, meu IDE preferido gerará automaticamente o bloco de comentários (se eu digitar / **), que executa aproximadamente 75% dos comentários para mim. É incrível quantas coisas estúpidas eu parei de cometer ao longo da minha vida de codificador apenas porque tive que explicar para outras pessoas (e para o futuro) o que estou fazendo. Quando meu comentário para o gerador de documentos é maior que o método, isso geralmente significa que eu não tomei café suficiente e talvez queira pensar um pouco mais.
Esses mesmos blocos de comentários também criam o texto de "ajuda" de conclusão em linha para que eu possa ver exatamente o que era esperado (pelos outros codificadores) enquanto escrevia a chamada de função. Este é um enorme aumento de produtividade para mim (especialmente naqueles casos raros em que outros desenvolvedores úteis escreveram "pelo amor de Deus, faça / não faça X" - o que pode economizar muita dor.
Não posso enfatizar o suficiente como é útil ter os tipos de entrada esperados especificados em projetos PHP complexos (e frequentemente mal nomeados) e a ordem dos argumentos nos métodos menos usados. Mesmo com meu próprio código, nem sempre consigo lembrar quais argumentos especifiquei para algo que não toquei em uma época.
Em um exemplo, significava que a fonte dos problemas recorrentes era que, por algum motivo que reflete mal em desenvolvedores anteriores, algumas funções e até constantes foram definidas em um grande número de lugares (com um grau de inconsistência para adicionar "diversão") . Esse era o sinal para se afastar do projeto.
Em projetos maiores que começaram antes de eu entrar, posso ver qual desenvolvedor (supondo que eles tenham marcado o arquivo da classe com um nome e um email) criou a classe e simplesmente poder encontrar e conversar com o desenvolvedor certo é extremamente útil.
Listas de tarefas automáticas - usar a tag @todo (comum nos tipos de projetos em que trabalho) significa que a documentação pode acompanhar as coisas que precisam de mais trabalho (ou os recursos que faltam). Mais uma vez, meu IDE acompanha isso e isso por si só atua como um bom guia sobre o que precisa primeiro de minha atenção.
Por fim (e muito importante para mim), ele remove a sobrecarga não trivial de escrever tudo isso e, em seguida, tenta mantê-lo atualizado quando alguns (muitos leitores) cometem alterações e não conversam com os mantenedores da documentação.
Portanto, os motivos incluem:
- Economizando para desenvolvedores posteriores uma pilha de tempo,
- Mantendo o controle de onde as funções são chamadas (e definidas),
- Detecção de codificação boba,
- Encontrar (como outro apontou) quando algo está obviamente faltando,
- Simplificando a refatoração (nunca é muito divertido)
- (Em muitos casos), ter uma idéia do que o desenvolvedor estava tentando fazer (supondo que ele tenha deixado algumas anotações).
- Se o projeto for complexo o suficiente para ter várias licenças em andamento (sem graça), posso ver rapidamente quais licenças se aplicam a qualquer seção. É certo que este é um bônus adicional.
- Obtendo uma idéia de com quem conversar sobre um arquivo de projeto.
- Listas de tarefas automáticas
Além disso, não subestime o valor de manter os chefes de cabelos pontudos felizes com o toque de um botão.
Em suma, os "comentários da documentação automática" são vitais para meus hábitos de codificação. Tenho certeza de que muitos pensam que isso é manco, mas também tenho a certeza de que existem poucas pessoas que sabem exatamente o que estou dizendo. Não sei como sobrevivi antes de descobrir o phpXRef (e meu IDE favorito).