Qual è lo scopo di queste properties; PHPDOC?

In generale, le properties; PHPDOC sono autoesplicative, ma sto avendo difficoltà a comprenderle:

@category : cos'è esattamente?

@package : qualcuno potrebbe fornirmi esempi sull'utilizzo di questa properties;?

Il tag del pacchetto è il tag di organizzazione chiave che usi nel tuo codice. Quando phpDocumentor genera i documenti, raccoglie gli elementi nei pacchetti che imposti. In alcuni casi, è ansible scegliere di utilizzare solo un nome pacchetto (@package MyPackage) per l'intera base di codice, in modo che tutti i file, le classi e così via vengano visualizzati nei documenti del pacchetto.

Tuttavia, se si sceglie di organizzare le cose in modo più modulare, si potrebbero avere tutti i file procedurali con interface Web in un unico pacchetto (pagine Web @package), tutte le classi che affrontano il database in un pacchetto (@package DatabaseHandlers), tutte le classi di utilità in un pacchetto ( @package Utilites), e così via.

La cosa fondamentale da ricordare su @package è che è la tua strada per organizzare i documenti … non ha nulla a che fare con il modo in cui il codice viene eseguito. Ora, è più probabile che tu voglia organizzare i documenti in base al modo in cui organizzi concettualmente i pezzi della tua app in testa, in modo che in questo senso, "pacchetto" si senta come se stesse organizzando il codice Ma in Alla fine, il tag del pacchetto è tutto su come vuoi phpDocumentor per organizzare i documenti.

Per quanto riguarda il tag di categoria, non credo che nessuno dei convertitori di output utilizzi questo tranne quello (i) che interessa al progetto PEAR. La categoria viene utilizzata per raccogliere set di pacchetti in un unico grande pacchetto. Ma ancora una volta, questo è rilevante solo per PEAR, per quanto riguarda le capacità già inserite nei convertitori di output. Puoi ignorare questo tag se vuoi … non puoi ignorare il tag del pacchetto, perché è il nucleo di come phpDocumentor organizza i documenti.

Ora, per quanto riguarda gli esempi di utilizzo di @package, ce ne sono alcuni nel manuale, come già visto. Per farla breve, è necessario un tag pacchetto nel docblock a livello di file di each file (questo è il punto in cui le funzioni e le costanti a livello globale otterrebbero il loro "pacchetto") e nel docblock di each class. Se non si forniscono i valori del pacchetto per questi elementi del codice, phpDocumentor è costretto a scaricarli tutti in un pacchetto "predefinito".

Ultimo punto … se non ti interessa organizzare il tuo codice in vari pacchetti e non vuoi modificare tutti i tuoi file per aggiungere i tag @package, puoi usare l'argomento -dn runtime per impostare un pacchetto predefinito nome [1]. Questo dice a phpDocumentor di usare il nome del pacchetto fornito in quell'argomento per tutti gli elementi di codice "non pacchettizzati" per i quali vuole il nome di un pacchetto. Esiste anche un argomento -dc per impostare un nome di categoria predefinito, ma questo è molto less critico di un bisogno per quanto riguarda phpDocumentor.

[1] – http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.defaultpackagename

(Includevo più URL, ma StackOverflow non mi consente di pubblicare più di uno …)

@categoria

Il tag @category viene utilizzato per organizzare gruppi di pacchetti insieme.

Questo è direttamente applicabile al converter XML: DocBook / peardoc2 e può essere utilizzato da altri convertitori. Altri convertitori confezionati con phpDocumentor ignorano la categoria, ma questo potrebbe cambiare nelle versioni future. È anche ansible specificare dynamicmente la categoria utilizzando l'opzione della row di command -dc, –defaultcategoryname

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.category.pkg.html

@pacchetto

@package può essere utilizzato solo per documentare pagine o classi procedurali.

I pacchetti vengono utilizzati per aiutare a raggruppare logicamente gli elementi correlati. Si scrivono classi per raggruppare funzioni e dati correlati insieme e phpDocumentor rappresenta il contenuto dei file (funzioni, definisce e include) come "Pagine procedurali". Un pacchetto viene utilizzato per raggruppare le classi e le pagine procedurali nello stesso modo in cui una directory raggruppa i file correlati.

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.package.pkg.html