Newsgroup: it.comp.www.php
Titolo: testare la correttezza dei DocBlock

/**
  * @see xyz
  */
function abc() {}
 
/**
  * @see abD
  */
function xyz() {}
 
Apparentemente sembra tutto apposto, ma il DocBlock della seconda 
funzione ha un piccolo errore: al posto di *abc* è stato scritto *abD*.
Purtroppo polo un programmatore molto attento riuscirebbe ad accorgersi 
di queste sottigliezze.
Quindi, dato che per testare il funzionamento di un'applicazione, di 
solito si scrivono appositi unitari e funzionali, non si potrebbero 
anche scrivere dei test per testare la correttezza dei DocBlock?

 polo un programmatore molto attento
 
*solo* un programmatore molto attento, scusate :D
 


 
E perché non scrivere i test per i test? :)
 
Nah, non ne vale la pena: tanto se usi un tool per generare la documentazione
te ne accorci subito se qualcosa nei commenti è sbagliato!
 
Ciao!


un tool tipo?


Ce ne sono vari, phpDocumentor è quello che uso ultimamente..
 
Se non usi niente per generare la documentazione in automatico non ha senso
usare i DocBlock in primo luogo (almeno che non li usi per le annotations
tipo per Doctrine o simili).
 
Ciao!

 tipo per Doctrine o simili).
 
ho provato ad usare questo phpDocumentator mai i @see errati nome li segnala
 


Se il @see è sbagliato nella documentazione non avrai i link giusti..
 
Ciao!


ovvio, e quindi non andrebbero segnalati dapprima?
Ma oltre a questo vedo mi pare che i @see non vengono proprio elaborati, 
mi sembra :-|

 mi sembra :-|
 
Questo credo dipenda dal template di default (il "clean") - con altri template
i @see dovrebbero vedersi.
 
Ciao!

 i @see dovrebbero vedersi.
 
allora sentimi.
Ho fatto questo file
 
<?php
/**
  * Som
  */
 
/**
  * Sommario
  * @see abD()
  */
function xyz() {
 
}
 
 
Do il comando
 
phpdoc --directory mio_progetto --target /tmp/docs --template="checkstyle"
 
non viene segnalato un bel niente!!!
Il template non va bene? Quale devo usare?


 
Il "checkstyle" se non sbaglio non genera nulla, fa solo il check della
correttezza. Se usi un template che genera l'HTML, come il "clean", o il "zend"
i @see seguiti da un riferimento interno dovrebbero diventare link sulle
pagine (dico sempre "dovrebbero" perché dipende dal template e non ricordo
chi fa cosa)
 
Ciao!

 chi fa cosa)
 
cmq sicuramente non è lo strumento che fa per me, mi sa che non hai 
letto bene il post iniziale...


Sì, l'ho letto e l'ho capito, cercavo di metterlo in un'ottica pratica.
I DocBlock li usi o per generare la documentazione in automatico o per generare
degli "hints" per il tuo IDE. In entrambi i casi è immediato accorgersi che
qualcosa non va.
Più nello specifico cercavo di dirti che il @see non serve a quello che pensavi
servisse: la sintassi più comune non è "@see [FQSEN]", per cui non credo ci sia
un tool che invece l'interpreti come vuoi te. Niente però ti vieta, per
esempio, di fare una patch per phpdoc o, meglio ancora, usare un'altra tag che
meglio ricalca quello che vuoi ottenere.
 
Ciao!

 meglio ricalca quello che vuoi ottenere.
 
ad esempio?
 


 
E che ne so, dipende da te.. @uses?
 
Ciao!


ok, farò un po' di prove.
Ma nella documentazione generata, vedo che non c'è una casella per 
cercare gli argomenti digitando delle parole chiave.
Si può farla generare?
 


 
Buona domanda, mi sa che phpdoc non ha un search out-of-the-box tipo quello
di doxygen o apigen, almeno, io non lo trovo :/
Boh, dovrei cercare anch'io un po' per rispondere.
 
Ciao!