Sto aggiungendo la documentazione al codice PHP usando lo strumento phpDocs:
/**
* This is a summary
*
* This is a description
*
* @use This function is called here and here
*/
function doSomething(){
}
Mi sto solo chiedendo se voglio aggiungere all'interno di questo docblock un tag 'use' che dice dove viene chiamata la funzione doSomething () come faccio a farlo correttamente?
Non farlo. Non esiste un modo corretto di farlo.
La documentazione da cui viene chiamata una funzione è un residuo del paradigma programmazione strutturata degli anni settanta e ottanta. Ricordo davvero nel 1989 un professore che ci chiedeva di documentare le funzioni in questo modo; Non ho mai sentito nessuno che faccia una cosa del genere da allora. Questo paradigma è morto da oltre due decenni. Ci siamo trasferiti.
Una funzione che non regge da sola non vale la pena avere. Se una funzione in effetti è autonoma, quindi chi la chiama non interessa alla funzione, non influenza ciò che fa la funzione, né come lo fa. Quindi, davvero non ti interessa chi lo chiama. Chiunque può chiamarlo e non hanno bisogno dell'autorizzazione di un commento del doc per farlo.
Per dirla in parole diverse, una funzione ben scritta è per definizione una funzione che non ha bisogno, e non dovrebbe, preoccuparsi di chi la chiama. Includendo le informazioni su chi la chiama nella sua documentazione, stai tentando il lettore di sospettare che questa funzione possa in qualche modo essere strettamente accoppiata con questi particolari chiamanti, costringendo il lettore a ricontrollare per assicurarsi che di fatto non lo è, perché l'accoppiamento stretto sarebbe una cosa terribile da fare.
Inoltre, l'insieme di luoghi che chiamano una determinata funzione tende a cambiare drasticamente mentre continui a lavorare sulla base di codice, quindi questo particolare tipo di documentazione diventa obsoleto molto veloce , mentre allo stesso tempo è qualcosa che puoi chiedere al tuo IDE in qualsiasi momento semplicemente premendo una combinazione di tasti, (solitamente si chiama "Trova riferimenti" o qualcosa di simile) e l'IDE ti dirà in millisecondi, e lo farà in modo molto più preciso di qualsiasi documentazione lo farebbe mai.
Quindi: assolutamente inutile.
Leggi altre domande sui tag php documentation documentation-generation