Share
A questo punto della serie, abbiamo coperto molto materiale: non solo abbiamo coperto le basi della programmazione orientata agli oggetti, ma abbiamo anche iniziato a creare un plug-in completamente funzionale.
Ma la sfida che arriva con il lavoro che abbiamo fatto finora è che non include alcuna documentazione su come funziona effettivamente il plugin. Se ricordi l'articolo precedente, abbiamo preso una decisione consapevole sullo sviluppo di posticipare questa funzione.
A partire da questo articolo, daremo un'occhiata in due parti su come documentare i plugin di WordPress e come possiamo farlo dato il nostro attuale plugin.
Prima di procedere con il resto di questo articolo, ti esorto vivamente a recuperare il contenuto che abbiamo trattato fino ad ora. Come accennato in ogni articolo passato, ogni articolo si basa sul precedente articolo della serie.
Detto questo, è tempo di rivolgere la nostra attenzione alla documentazione del nostro plug-in, ma prima di andare avanti e farlo, dobbiamo assicurarci di comprendere appieno gli standard che sono in vigore per noi per documentare il nostro lavoro.
Quindi, prima di fornire i commenti rilevanti per il nostro plug-in, daremo un'occhiata a ciò che abbiamo bisogno di includere. Dopodiché, vedremo come fare esattamente questo per il nostro plugin nel prossimo articolo.
Per cominciare, il Codice WordPress include un manuale specifico per gli standard di documentazione PHP. Puoi leggere gli standard nella loro interezza; tuttavia, stiamo mettendo in evidenza le caratteristiche più importanti di ciò che implementeremo nel prossimo articolo.
Le cose principali che ci occupiamo della documentazione sono le seguenti:
Accentsconagua
richiedere dichiarazioniQuesto sarà ovviamente un insieme di articoli più lento rispetto ai precedenti due, ma vista la quantità di lavoro che abbiamo trattato fino ad ora, dovrebbe essere un gradito cambiamento di ritmo per alcuni lettori.
Quindi, detto questo, cominciamo.
Le intestazioni dei file sono uniche nel fatto che sono qualcosa di simile dovrebbero essere inserito in ogni file dei file che compongono un plugin (o un tema, ma non è il focus di questa serie), ma non sono sempre.
Secondo il codice:
Il blocco intestazione del file PHPDoc viene utilizzato per fornire una panoramica di ciò che è contenuto nel file.
Il modello generale che utilizzeremo a partire dal prossimo articolo ha il seguente aspetto:
/ ** * Breve descrizione (nessun punto per le intestazioni dei file) * * Descrizione lunga. * * @link URL * @since x.x.x (se disponibile) * * @package WordPress * Componente @subpackage * /
Si noti che nelle intestazioni dei file, lo facciamo non includi un punto e ci sono due componenti della descrizione:
Ogni volta che li scrivo per i miei progetti specifici, cerco di immaginare che la mia breve descrizione se qualcosa che può rientrare nella parte superiore di LEGGIMI file, che può essere un singolo, breve passo dell'elevatore per il file, o quello potrebbe anche essere contenuto in qualcosa di corto come un tweet.
La descrizione più lunga, ovviamente, può essere facilmente più dettagliata di quanto ci piace. In questo caso, c'è un formato specifico che dovremmo usare per una lunga descrizione, ma questo va oltre lo scopo di questo particolare articolo, come vedremo un particolare esempio pratico di questo nel prossimo articolo della serie.
richiedere dichiarazioniOccasionalmente, abbiamo la necessità di documentare il codice che è incluso in una funzione o in una classe. Questi sono diversi da definizioni di funzioni o definizioni di variabili di classe.
Invece, pensa a questi come commenti in linea per quando è necessario includere o richiedere una certa dipendenza. Questo sarà generalmente uno script PHP separato su qualsiasi altra cosa.
Per esempio:
/** * Breve descrizione. (usa periodo) * / require_once (ABSPATH. '/filename.php');
Tuttavia, si noti che in base al Codex questo è non limitato solo a chiamate di funzione come require_once.
I file richiesti o inclusi devono essere documentati con una breve descrizione del blocco PHPDoc. Facoltativamente, questo può essere applicato alle chiamate in linea get_template_part () necessarie per chiarezza.
Dal momento che il nostro plugin sta effettuando chiamate direttamente su script esterni, noi volontà utilizzare un esempio pratico di questo nel prossimo articolo. La ragione per cui la condivido qui non è solo quella di prepararci per quello che sta arrivando, ma anche di mostrare il formato corretto su come sfruttare questo in qualsiasi corrente che potremmo fare.
Anche se penso che tutta la documentazione sia importante, e non sto affermando che questi due aspetti sono la parte più importante della documentazione di un plugin; tuttavia, dato che il nostro plugin è di natura orientata agli oggetti, è fondamentale capire come documentare correttamente sia le nostre classi sia le nostre funzioni.
Le definizioni di classe sono commenti al codice che appaiono tra le intestazioni dei file (che abbiamo discusso sopra) e il nome della classe.
Il formato utilizzato per documentare una classe è il seguente:
/** * Breve descrizione. (usare periodo) * * Descrizione lunga. * * @since x.x.x * * @see Funzione / metodo / classe invocata * @link URL * /
Se ti capita di guardare il codice WordPress per questo articolo, noterai che fornisce a poco maggiori informazioni che ho incluso nella documentazione sopra. Questo perché hanno incluso il contenuto di entrambe le classi e definizioni di funzioni.
Invece, li interrompiamo ciascuno in aree separate per riferimenti futuri e in modo che possiamo capire perché documenteremo determinate cose in determinati modi nel prossimo articolo della serie.
Simile alle definizioni di classe, che puoi aspettarti di vedere quanto segue:
/** * Breve descrizione. (usare periodo) * * Descrizione lunga. * * @since x.x.x * @access (per funzioni: usa solo se privato) * * @see Funzione / metodo / classe invocata * @link URL * @global tipo $ varname Breve descrizione. * * @param type $ var Descrizione. * @param type $ var Facoltativo. Descrizione. * @return type Descrizione. * /
Si noti nel commento del codice sopra, c'è pochissima differenza rispetto a ciò che abbiamo visto con la documentazione di classe.
Oltre a ciò che è sopra, vediamo le informazioni per:
Ovviamente, questo materiale non è tipicamente usato nel contesto di una classe; tuttavia è usato nel contesto di una funzione.
A tal fine, ecco come puoi pensare a ciascuno dei precedenti:
globale le variabili si riferiscono a quelle variabili utilizzate nel contesto della funzione che sono globali all'ambiente WordPress. Questo include cose come $ postale, $ authordata, e altri elencati qui.@param il tag si riferisce alle variabili accettate da una funzione. Ovviamente, questo include il tipo di variabile che accetta e una descrizione di ciò che rappresenta la variabile.@ritorno tag discute il tipo di variabile restituito da una funzione e una breve descrizione del tipo di dati restituiti.Piuttosto che dare un esempio concreto di questo qui, lo faremo nel post di follow-up con il codice che abbiamo scritto nel post precedente.
Infine, le proprietà variabili - o più comunemente conosciute come proprietà di classe (che a volte sono chiamate attributi), rappresentano i dati contenuti nella classe.
Ricordate da prima nella nostra serie, abbiamo menzionato che gli attributi sono come gli aggettivi che descrivono il nome che la classe rappresenta.
Come puoi vedere dal precedente articolo, le proprietà della classe sono definite subito dopo il nome della classe e prima del costruttore (indipendentemente dal fatto che pubblico o privato).
Per documentare questi attributi, seguiamo il seguente modello:
/** * Breve descrizione. (usa periodo) * * @since x.x.x * @access (privato, protetto o pubblico) * @var tipo $ var Descrizione. * /
Abbastanza facile da capire.
Alcuni potrebbero obiettare che l'uso di @accesso è frivolo in quanto il modificatore di accesso della funzione che segue direttamente il commento spiega il tipo di funzione che è.
Ma questo è dove le differenze negli standard di documentazione di WordPress differiscono da alcuni standard PHP (sia in atto che in via di standardizzazione).
In breve, la PSR fa riferimento alle raccomandazioni standard di PHP proposte dal PHP Framework Interop Group.
Puoi leggere su ciascuno di questi standard qui:
Quale PSR-5 viene discusso in questo momento. Questi sono importanti da seguire per tutti gli sviluppatori PHP indipendentemente dalla piattaforma o dalle fondamenta che stanno utilizzando, ma penso anche che valga la pena notare che le differenze (e le similarità) esistenti tra PSR e gli standard di WordPress come siamo differenze.
Questo è un punto di disaccordo, quindi quello che sto per dire è puramente soggettivo; tuttavia, sono dell'opinione che quando lavori in WordPress, devi seguire le convenzioni proposte da WordPress.
Questo non vuol dire che non dovremmo sforzarci di allinearci più strettamente con ciò che sta facendo la comunità PHP più ampia; tuttavia, se stiamo scrivendo codice WordPress per altri sviluppatori di WordPress, questo è qualcosa su cui dovremmo concentrarci principalmente.
Nel prossimo articolo, daremo un'occhiata all'applicazione dei principi sopra riportati nel contesto del nostro plugin.
Questo dovrebbe aiutarci non solo a costruire un plug-in che sia altamente conforme agli standard di codifica di WordPress, ma anche agli standard della documentazione in modo tale che noi, i nostri utenti e i nostri futuri contributori saranno in grado di seguire facilmente il flusso del controllo attraverso il progetto.
Nel frattempo, sentiti libero di lasciare qualsiasi domanda e / o commento nel feed qui sotto!
