Share
Op dit punt in de serie hebben we veel materiaal behandeld - niet alleen hebben we de basisprincipes van objectgeoriënteerd programmeren behandeld, maar we zijn ook begonnen met het bouwen van een volledig functionele plug-in.
Maar de uitdaging die hoort bij het werk dat we tot nu toe hebben gedaan, is dat het geen documentatie bevat over hoe de plug-in echt werkt. Als je je herinnert uit het vorige artikel, hebben we een bewust ontwikkelingsbesluit genomen om deze functie uit te stellen.
Vanaf dit artikel gaan we een tweedelige blik werpen op het documenteren van WordPress-plug-ins en hoe we dit kunnen doen met onze huidige plug-in.
Voordat ik verder ga met de rest van dit artikel, raad ik u aan de inhoud die we tot nu toe hebben behandeld in te halen. Zoals vermeld in elk vorig artikel, bouwt elk artikel voort op het vorige artikel in de serie.
Met dat gezegd, is het tijd om onze aandacht te richten op het documenteren van onze plug-in, maar voordat we verder gaan, moeten we ervoor zorgen dat we volledig de standaarden begrijpen die er zijn om ons werk te documenteren..
Dus voordat we de opmerkingen geven die relevant zijn voor onze plug-in, gaan we kijken wat we allemaal moeten toevoegen. Daarna zullen we kijken naar precies hetzelfde doen voor onze plug-in in het volgende artikel.
Om te beginnen bevat de WordPress Codex een handboek specifiek voor de PHP-documentatienormen. Je kunt de normen in hun geheel lezen; we zullen echter de belangrijkste kenmerken benadrukken van wat we in het volgende artikel gaan implementeren.
De belangrijkste dingen die we ons bezighouden met het documenteren zijn de volgende:
Accentsconagua
vereisen statementsDit zal natuurlijk een veel langzamer tempo van artikelen zijn dan de vorige twee, maar gezien de hoeveelheid werk die we tot nu toe hebben behandeld, zou het een welkome verandering van tempo moeten zijn voor sommige lezers..
Dus met dat gezegd, laten we beginnen.
Bestandsheaders zijn uniek in het feit dat ze iets zijn dat moeten worden geplaatst in elk bestand van de bestanden waaruit een plug-in (of een thema, maar dat is niet de focus van deze serie), maar ze zijn niet altijd.
Volgens de Codex:
Het PHPDoc-bestand header-blok wordt gebruikt om een overzicht te geven van wat er in het bestand staat.
De algemene sjabloon die we zullen gebruiken in het volgende artikel ziet er als volgt uit:
/ ** * Korte beschrijving (geen periode voor bestandsheaders) * * Lange beschrijving. * * @link URL * @since x.x.x (indien beschikbaar) * * @package WordPress * @subpackage Component * /
Merk op dat we dat in de bestandsheaders doen niet een periode opnemen en er zijn twee componenten van de beschrijving:
Telkens wanneer ik deze schrijf voor mijn specifieke projecten, probeer ik me in te beelden dat mijn korte beschrijving iets is dat in de top van kan passen Leesmij bestand, dat kan een enkele, korte elevator pitch zijn voor het bestand, of dat mei zelfs vervat zitten in iets dat zo kort is als een tweet.
De langere beschrijving kan natuurlijk net zo eenvoudig gedetailleerder zijn als we willen. In dit geval is er een specifieke indeling die we moeten gebruiken voor een lange beschrijving, maar dat valt buiten het bestek van dit specifieke artikel, omdat we hier een bijzonder, praktisch voorbeeld van zullen zien in het volgende artikel in de serie.
vereisen verklaringenAf en toe hebben we de behoefte om code te documenteren die is opgenomen in een functie of een klasse. Deze zijn anders dan functiedefinities of definities van klassenvariabelen.
Beschouw in plaats daarvan deze als inline opmerkingen voor wanneer u een bepaalde afhankelijkheid moet opnemen of vereisen. Dit zal over het algemeen een apart PHP-script zijn in plaats van iets anders.
Bijvoorbeeld:
/** * Korte beschrijving. (gebruik periode) * / require_once (ABSPATH. '/filename.php');
Merk echter op dat volgens de Codex dat dit is niet gewoon beperkt tot functieaanroepen zoals eenmalig benodigd.
Bestanden die nodig zijn of worden opgenomen, moeten worden gedocumenteerd met een korte beschrijving PHPDoc-blok. Optioneel kan dit van toepassing zijn op inline get_template_part () oproepen voor de duidelijkheid.
Omdat onze plug-in rechtstreeks naar externe scripts belt, wij zullen gebruik een praktisch voorbeeld hiervan in het volgende artikel. De reden dat ik het hier deel, is niet alleen om ons voor te bereiden op wat er gaat komen, maar ook om het juiste formaat te laten zien voor hoe we dit kunnen gebruiken in elke stroming die we misschien aan het doen zijn.
Hoewel ik denk dat alle documentatie belangrijk is, en ik beweer niet dat deze twee aspecten het belangrijkste onderdeel zijn van het documenteren van een plug-in; Omdat onze plug-in echter objectgeoriënteerd van aard is, is het van cruciaal belang dat we begrijpen hoe we onze klassen en onze functies correct kunnen documenteren.
Klasse-definities zijn code-opmerkingen die verschijnen tussen de bestandsheaders (die we hierboven hebben besproken), en de naam van de klasse.
Het formaat dat wordt gebruikt om een klasse te documenteren is als volgt:
/** * Korte beschrijving. (gebruik periode) * * Lange beschrijving. * * @since x.x.x * * @see Functie / methode / klasse gebaseerd op * @link URL * /
Als je toevallig naar de WordPress Codex voor dit artikel kijkt, zul je merken dat het een weinig meer informatie die ik heb opgenomen in de bovenstaande documentatie. Dit komt omdat ze inhoud beide klassen hebben opgenomen en functiedefinities.
In plaats daarvan breken we ze allemaal uit in afzonderlijke gebieden voor toekomstig gebruik en zodat we kunnen zien waarom we bepaalde dingen op bepaalde manieren zullen documenteren in het volgende artikel in de serie.
Vergelijkbaar met klassedefinities, die u kunt verwachten het volgende te zien:
/** * Korte beschrijving. (gebruik periode) * * Lange beschrijving. * * @since x.x.x * @access (voor functies: alleen gebruiken als privé) * * @see Functie / methode / klasse gebaseerd op * @link URL * @global-type $ varname Korte beschrijving. * * @param type $ var Beschrijving. * @param type $ var Optioneel. Omschrijving. * @return type Beschrijving. * /
Let op in de bovenstaande codecommentaar, er is heel weinig verschil met wat we zagen met klassedocumentatie.
Naast wat hierboven staat, zien we informatie voor:
Vanzelfsprekend wordt dit materiaal niet typisch gebruikt binnen de context van een klasse; echter, het is gebruikt binnen de context van een functie.
Om dat te bereiken, hier is hoe u elk van de bovenstaande kunt bedenken:
globaal variabelen verwijzen naar die variabelen die worden gebruikt in de context van de functie die globaal zijn voor de WordPress-omgeving. Dit omvat dingen zoals $ bericht, $ authordata, en anderen die hier worden vermeld.@param tag verwijst naar de variabelen die een functie accepteert. Vanzelfsprekend omvat dit het type variabele dat het accepteert en een beschrijving van wat de variabele vertegenwoordigt.@return tag bespreekt het type variabele dat een functie retourneert en een korte beschrijving van het type gegevens dat wordt geretourneerd.In plaats van hier een concreet voorbeeld van te geven, doen we dit in de follow-up post met de code die we in de vorige post hebben geschreven.
Ten slotte vertegenwoordigen variabele eigenschappen - of beter bekend als klasse-eigenschappen (die soms attributen worden genoemd), de gegevens die in de klasse worden bewaard.
Onthoud van eerder in onze serie dat attributen zijn als de adjectieven die het zelfstandig naamwoord beschrijven dat de klasse vertegenwoordigt.
Zoals u kunt zien in het vorige artikel, worden klasse-eigenschappen gedefinieerd net na de naam van de klasse en vóór de constructor (ongeacht of deze openbaar of privaat).
Om deze kenmerken te documenteren, volgen we de volgende sjabloon:
/** * Korte beschrijving. (gebruik periode) * * @since x.x.x * @ toegang (privé, beschermd of openbaar) * @var type $ var Beschrijving. * /
Makkelijk genoeg om te begrijpen.
Sommigen beweren dat het gebruik van @toegang is lichtzinnig omdat de toegangsmodificator van de functie die direct volgt op de opmerking, het type functie verklaart dat het is.
Maar dit is waar de verschillen in de WordPress-documentatiestandaarden verschillen van enkele van de PHP-standaarden (zowel op hun plaats als die welke worden gestandaardiseerd).
Samengevat, PSR verwijst naar de PHP-standaardaanbevelingen zoals voorgesteld door de PHP Framework Interop Group.
U kunt hier over elk van deze standaarden lezen:
Welke PSR-5 wordt momenteel besproken. Deze zijn belangrijk om te volgen voor alle PHP-ontwikkelaars, ongeacht het platform of de stichting die ze gebruiken, maar ik denk ook dat het de moeite waard is om op te merken dat de verschillen (en overeenkomsten) tussen PSR en de WordPress-standaarden daar zijn zijn verschillen.
Dit is een punt van onenigheid, dus wat ik ga zeggen is puur subjectief; echter, ik ben van mening dat wanneer je binnen WordPress werkt, je de conventies zoals voorgesteld door WordPress moet volgen.
Dit wil niet zeggen dat we ons niet moeten inspannen om ons beter af te stemmen op wat de grotere PHP-gemeenschap doet; Als we echter WordPress-code schrijven voor andere WordPress-ontwikkelaars, dan is dit iets waarop we ons vooral moeten richten.
In het volgende artikel gaan we kijken naar het toepassen van de bovenstaande principes in de context van onze plug-in.
Dit zou ons moeten helpen om niet alleen een plug-in te bouwen die in hoge mate voldoet aan de coderingsstandaarden van WordPress, maar ook om de documentatienormen zodanig te implementeren dat wij, onze gebruikers en onze toekomstige medewerkers de stroom van controle eenvoudig door het project heen kunnen volgen..
In de tussentijd kunt u vragen en / of opmerkingen achterlaten in de onderstaande feed!
