Come spostare la documentazione php più vicina agli standard?

Question

Come spostare la documentazione php più vicina agli standard?

#1 da (3 voti)

4

Ho un grande progetto php. Ho usato per documentarlo con NaturalDocs, ma non ho incluso la generazione della documentazione nel processo di compilazione per molto tempo (anni).

Recentemente ho iniziato a usare il compositore e ho esaminato il PSR. L'unico modo standard per documentare il mio codice sembra essere docblocks per phpdocumentor.

Dato che il mio codice è solo in parte orientato agli oggetti e contiene molti file procedurali, non posso fare affidamento solo sulla documentazione di classi e funzioni, ma ho un sacco di documentazione a livello di file.

Si scopre che i docblock a livello di pagina non sono ben supportati in phpdocumentor (vedi link ). Quindi sono davvero bloccato ora.

Per concludere le mie domande:

Ha senso documentare codice non orientato agli oggetti con docblocks e phpdocumentor? Phpdocs è una buona scelta qui? Il mio approccio per professionalizzare la documentazione del nostro progetto è fattibile o è in qualche modo imperfetto?

programming-practices php documentation

posta Lorenz Meyer 17.11.2014 - 13:19

fonte

1 risposta

Leggi altre domande sui tag programming-practices php documentation

Comunicazione / aggiornamenti tra unità di lavoro / contesti di strutture entità, in conflitto con le modifiche dell'utente Perché la macchina per la realizzazione di punte di Shannon ha battuto quella di Hagelbarger?

score 3 · Answer 1

Continuo a pensare che abbia senso attenersi a phpDoc per documentare il codice PHP. È lo standard raccomandato dal progetto php PSR . È anche generalizzato nel concetto di annotazioni, poiché è utilizzato ad esempio in Doctrine . Un altro argomento per phpDoc è che Javascript e molti altri linguaggi hanno il suo sistema di commento analogico.

Dopo molto tempo passato a provare a far funzionare phpDocumentor, ho generato la documentazione con Doxygen . Ci sono chiari vantaggi rispetto a phpDocumentor:

Funziona fuori dagli schemi. Non è necessario gestire host di bug.
Flessibilità: ci sono molte più opzioni con doxygen.
I docblock a livello di pagina funzionano immediatamente (avvio del docblock con @file ).
È possibile documentare tutte le entità, anche se non hanno documenti. Ciò consente di ottenere un doc completo di tutte le classi, funzioni e vars nel progetto, senza iniziare a documentare. Questo vale per il principio DRY e consente di documentare manualmente ciò che è importante. Puoi documentare l'immagine più grande e lasciare che Doxygen enumeri tutti gli argomenti della funzione ...
È più veloce generare il documento
Il documento è più bello.

L'unico inconveniente che ho trovato è che non puoi attaccare da 1 a 1 alla proposta standard PSR-5:

@var è deprecato a favore di @type , ma doxygen comprende solo @var.
@file è necessario, ma non esiste come tag phpDoc .

Ma phpDocumentor non onora né lo standard phpDoc (ad es. il metodo consigliato per descrive gli hash non è compreso da phpDocumentor).

Conclusione

Avere una documentazione completa del codice è un must. Semplifica il lavoro e dà sollievo.

Per me la documentazione è fondamentale, quindi è difficile capire che PHP Interop Group Framework fornisce raccomandazioni sulla documentazione, che no generatore di documentazione compies to.