Share
På dette punktet i serien har vi dekket mye materiale - ikke bare har vi dekket grunnleggende om objektorientert programmering, men vi har også begynt å bygge et fullt funksjonelt plugin.
Men utfordringen som følger med arbeidet som vi har gjort så langt er at det ikke inneholder noen dokumentasjon om hvordan plugin faktisk fungerer. Hvis du husker fra forrige artikkel, tok vi en bevisst utviklingsavgjørelse for å utsette denne funksjonen.
Fra denne artikkelen skal vi ta en todelte titt på hvordan du dokumenterer WordPress-plugins, og hvordan vi kan gjøre det, gitt vårt nåværende plugin.
Før du fortsetter med resten av denne artikkelen, oppfordrer jeg deg til å hente innholdet som vi har dekket så langt. Som nevnt i hver tidligere artikkel, bygger hver artikkel på forrige artikkel i serien.
Med det sagt er det på tide å gjøre oppmerksom på å dokumentere pluginet vårt, men før vi går videre og gjør det, må vi sørge for at vi fullt ut forstår de standarder som er på plass for oss å dokumentere vårt arbeid.
Så før du gir kommentarene som er relevante for vårt plugin, skal vi se på hva vi trenger å inkludere. Etter det ser vi på å gjøre akkurat det for vårt plugin i neste artikkel.
For det første inneholder WordPress Codex en håndbok spesielt for PHP Documentation Standards. Du kan lese standardene i sin helhet; Vi skal imidlertid fremheve de viktigste funksjonene i det vi skal implementere i neste artikkel.
De primære tingene som vi er opptatt av med å dokumentere, er følgende:
Accentsconagua
krever uttalelserDette vil selvsagt være et mye langsommere sett med artikler enn de to foregående, men i forhold til det arbeidet vi har dekket så langt, bør det være en velkommen endring i tempoet for noen lesere.
Så med det sagt, la oss komme i gang.
Filoverskrifter er unike i det faktum at de er noe som bør plasseres i hver fil av filene som utgjør et plugin (eller et tema, men det er ikke fokus for denne serien), men de er ikke alltid.
I henhold til Codex:
PHPDoc-filtekstblokken brukes til å gi en oversikt over hva som er inneholdt i filen.
Den generelle malen som vi bruker ved å starte i neste artikkel ser slik ut:
/ ** * Kort beskrivelse (ingen periode for filoverskrifter) * * Lang beskrivelse. * * @link URL * @since x.x.x (hvis tilgjengelig) * * @package WordPress * @subpackage Komponent * /
Legg merke til at i filoverskriftene gjør vi ikke inkludere en periode og det er to komponenter i beskrivelsen:
Når jeg skriver disse ut for mine spesifikke prosjekter, prøver jeg å forestille meg at min korte beskrivelse om noe som kan passe i toppen av README fil, det kan være en enkelt, kort heishøyde for filen eller den kan selv være inneholdt i noe så kort som en tweet.
Den lengre beskrivelsen, selvfølgelig, kan være like lett mer detaljert som vi liker. I dette tilfellet er det et spesifikt format som vi burde bruke for lang beskrivelse, men det ligger utenfor omfanget av denne spesifikke artikkelen, da vi ser et spesielt praktisk eksempel på dette i neste artikkel i serien.
krever uttalelserAv og til har vi behov for å dokumentere kode som er inkludert i en funksjon eller en klasse. Disse er forskjellige enn funksdefinisjoner eller klassebara variabler.
I stedet tenk på disse som inline-kommentarer for når du trenger å inkludere eller kreve en viss avhengighet. Dette vil vanligvis være et eget PHP-skript over alt annet.
For eksempel:
/** * Kort beskrivelse. (bruk periode) * / require_once (ABSPATH. '/filnavn.php');
Vær imidlertid oppmerksom på at i henhold til Codex at dette er ikke bare begrenset til funksjonssamtaler som require_once.
Filer som kreves eller inkluderes, skal dokumenteres med en kort beskrivelse av PHPDoc-blokk. Eventuelt kan dette gjelde for inline get_template_part () samtaler etter behov for klarhet.
Siden vår plugin ringer direkte til eksterne skript, vi vil bruk et praktisk eksempel på dette i neste artikkel. Grunnen til at jeg deler den her, er ikke bare å forberede oss på hva som kommer, men også å vise riktig format for hvordan du kan utnytte dette i enhver strøm som vi kan gjøre.
Selv om jeg tror at all dokumentasjon er viktig, og jeg hevder ikke at disse to aspektene er den viktigste delen av å dokumentere et plugin; men med tanke på at vårt plugin er objektorientert i naturen, er det viktig at vi forstår hvordan vi skal dokumentere både våre klasser og våre funksjoner riktig..
Klasse definisjoner er kode kommentarer som vises mellom filoverskriftene (som vi diskuterte ovenfor) og navnet på klassen.
Formatet som brukes til å dokumentere en klasse, er som følger:
/** * Kort beskrivelse. (bruk periode) * * Lang beskrivelse. * * @since x.x.x * * @see Funksjon / metode / klasse stole på * @link URL * /
Hvis du ser på WordPress Codex for denne artikkelen, vil du legge merke til at den gir en litt mer informasjon som jeg har tatt med i dokumentasjonen ovenfor. Dette er fordi de har tatt med innhold i begge klassene og Funksjonsdefinisjoner.
I stedet bryter vi hver av dem ut i separate områder for fremtidig referanse, og slik at vi kan se hvorfor vi dokumenterer bestemte ting på bestemte måter i neste artikkel i serien.
I likhet med klassdefinisjoner, kan du forvente å se følgende:
/** * Kort beskrivelse. (bruk periode) * * Lang beskrivelse. * * @since x.x.x * @access (for funksjoner: Bruk bare hvis privat) * * @see Funksjon / metode / klasse påberatt * @link URL * @global type $ varname Kort beskrivelse. * * @param type $ var Beskrivelse. * @param type $ var Valgfritt. Beskrivelse. * @return type Beskrivelse. * /
Legg merke til i koden kommentaren ovenfor, det er svært lite forskjell på det vi så med klassedokumentasjon.
I tillegg til hva som står ovenfor, ser vi informasjon for:
Tydeligvis er dette materialet ikke vanligvis brukt innenfor konteksten til en klasse; men det er brukt i sammenheng med en funksjon.
For det formål, her er hvordan du kan tenke på hver av de ovennevnte:
global variabler refererer til de variablene som brukes innenfor konteksten til funksjonen som er global til WordPress-miljøet. Dette inkluderer ting som $ post, $ authordata, og andre som er oppført her.@param tag henviser til variablene som en funksjon aksepterer. Tydeligvis inkluderer dette typen av variabel som den aksepterer og en beskrivelse av hva variabelen representerer.@komme tilbake tag diskuterer typen av variabel som en funksjon returnerer og en kort beskrivelse av typen data som blir returnert.I stedet for å gi et konkret eksempel på dette her, vil vi gjøre dette i oppfølgingsposten med koden vi skrev i forrige innlegg.
Endelig representerer variable egenskaper - eller mer kjent som klassegenskaper (som noen ganger kalles attributter), dataene som holdes i klassen.
Husk fra tidligere i vår serie, nevnte vi at attributter er som adjektiver som beskriver substantivet som klassen representerer.
Som du kan se fra forrige artikkel, defineres klasseegenskaper like etter navn på klassen og før konstruktøren (uansett om dens offentlig eller privat).
For å dokumentere disse egenskapene følger vi følgende mal:
/** * Kort beskrivelse. (bruk periode) * * @since x.x.x * @access (privat, beskyttet eller offentlig) * @var type $ var Beskrivelse. * /
Lett nok å forstå.
Noen kan hevde at bruken av @adgang er frivolous siden tilgang modifikatoren av funksjonen direkte etter kommentaren forklarer hvilken type funksjon det er.
Men dette er hvor forskjellene i WordPress dokumentasjonsstandarder er forskjellige fra noen av PHP-standardene (både på plass og de som er i ferd med å bli standardisert).
Kort sagt, PSR refererer til PHP-standardanbefalinger som foreslått av PHP Framework Interop Group.
Du kan lese om hver av disse standardene her:
Hvilken PSR-5 diskuteres akkurat nå. Disse er viktige å følge for alle PHP-utviklere, uavhengig av plattformen eller fundamentet de bruker, men jeg synes også det er verdt å merke seg at forskjellene (og likhetene) som eksisterer mellom PSR og WordPress-standardene som der er forskjeller.
Dette er et punkt av uenighet, så det jeg bare skal si er rent subjektiv; Jeg er imidlertid av tankegangen at når du jobber innenfor WordPress, bør du følge konvensjonene som foreslått av WordPress.
Dette er ikke å si at vi ikke bør gjøre en innsats for å nøye justere oss med det større PHP-fellesskapet gjør; Men hvis vi skriver WordPress-kode for andre WordPress-utviklere, så er dette noe som vi primært bør fokusere på.
I neste artikkel skal vi se på å anvende de ovennevnte prinsippene i sammenheng med vårt plugin.
Dette skal hjelpe oss med å ikke bare bygge et plugin som i høy grad samsvarer med WordPress-kodingsstandardene, men også til dokumentasjonsstandardene slik at vi, våre brukere og våre fremtidige bidragsytere vil være i stand til å enkelt følge kontrollflyten gjennom prosjektet.
I mellomtiden er du velkommen til å legge igjen noen spørsmål og / eller kommentarer i feedet under!
