Koska osaamme jo kirjoittaa moniriviset kommentit, voimme käyttää joko kolmoislainausmerkkejä tai kolminkertaisia kaksoislainausmerkkejä. Käytämme dokumentaatiomerkkijonoa, kun haluamme kuvata toimintojamme, jotta voimme saada dokumentaation tarvittaessa. Jotkut IDE:t antavat sinulle dokumentaatiota viemällä hiiren nimen päälle ja toiset korostavat tiettyjä avainsanoja. Mutta tosiasia on, että NumPyn asiakirjat ovat paljon joustavampia kuin muilla kielillä. Docstring on merkkijonoliteraali, joka esiintyy funktion määritelmän alussa. Meidän on annettava tietyt arvot, kun käytämme dokumenttimerkkijonoja funktioissa, luokissa jne.
Kun käytät dokumenttimerkkijonoja funktioiden kanssa, meidän on välitettävä argumentit. Kun käytät niitä luokkien kanssa, välitämme attribuutit ja menetelmät. Moduulien tapauksessa meidän on annettava luettelo luokista ja funktioista. Paketin tapauksessa välitämme luettelon toiminnallisista moduuleista. Pohjimmiltaan asiakirjamerkkijonon tarkoitus on, kuten nimi selittää, että se auttaa koodimme dokumentoinnissa. Teemme dokumentaatiota, jotta jos joku käyttää koodiamme jatkossa, hän pystyy ymmärtämään koodimme ja koodimme takana olevan logiikan docstringin avulla. Sisäänrakennetuissa funktioissa on myös dokumenttimerkkijonoja; voimme käyttää help()-funktiota katsoaksemme sisäänrakennettujen funktioiden dokumenttisarjaa.
Kommenttien ja dokumenttien välillä on joitain eroja. Tulkit jättävät huomioimatta kommentit, mutta tulkit eivät jätä huomiotta asiakirjoja. Muistia on varattu asiakirjoille. Kommentti on koodin kuvaus, mutta toisaalta dokumenttimerkkijonot kertovat koodin tarkoituksen.
Syntaksi:
Syntaksi dokumenttimerkkijonojen kirjoittamiseen NumPyssä on:
'''Dokumenttijonoviesti'''
Tai
'''Docstring-viesti'''
Huomaa, että asiakirjamerkkijono ei ole funktio tai menetelmä, joten sillä ei ole oikeaa syntaksia. Ainoa asia, joka on huomioitava tässä, on se, että aloitamme dokumenttisarjan kolmella lainausmerkillä tai kolmella kaksoislainausmerkillä. Kirjoitamme koodin kuvauksen ja päätämme sen uudelleen kolmella lainausmerkillä tai kolmella kaksoislainausmerkillä lopussa. Asiakirjoihin ei ole pakollista kirjoittaa. Sinun tarvitsee vain laittaa kolme kerta- tai kaksoislainausmerkkiä ennen ja jälkeen merkkijonokuvauksen.
Esimerkki 1:
Ymmärtääksemme asiakirjoja paremmin, annetaan esimerkki. Tässä esimerkissä NumPy-kirjaston sisällyttämisen jälkeen yksinkertaisesti julistamme muuttujan 'a' ja toisen muuttujan 'b'. Sen jälkeen luomme dokumenttimerkkijonomme, joka sanoo 'lisätään 'a' ja 'b' muuttujat'. Meidän tapauksessamme tämä on helppo esimerkki, mutta jos koodimme on monimutkainen, tämä auttaa kooderia paljon ymmärtämään koodia. Tämän jälkeen summaamme muuttujat 'a' ja 'b' ja tallennamme niiden tulostuloksen toiseen muuttujaan, joka on 'c'. Lopuksi tulostetaan muuttujan 'c' arvo. Nyt suoritamme koodimme.
tuonti nuhjuinen kuten esim.a = 1
b = kaksi
''Lisätään a ja b muuttujat'''
c = a+b
Tulosta ( c )
Tämä on tulos annetusta koodinpalasta. Näemme, että järjestelmä ei ole antanut virheellistä syntaksia tai mitään koodimme riville 7. Lisäksi järjestelmä ei ole tulostanut dokumenttisarjaamme. Sen sijaan se tulosti vain muuttujamme 'c' tulosteen, jossa käskimme järjestelmäämme tulostaa. Tämä osoittaa, kuinka asiakirjat toimivat. Seuraavan kerran, kun uusi koodaaja yrittää työstää koodiamme, hän ymmärtää, mitä teemme dokumenttimerkkijonomme avulla. Mutta sitä ei tulosteta tulosteena, joten se ei häiritse koodin käyttäjää.
Esimerkki 2:
Suoritamme nyt monimutkaisen esimerkin ymmärtääksemme dokumenttisarjan toiminnan. Ensin sisällytämme NumPy-kirjaston ja kirjoitamme sitten doc-merkkijonon, jossa selitämme seuraavan koodirivin, jossa selitämme taulukon alustuksen. Lisäämme myös dokumenttimerkkijonot koodin toiseen osaan. Jos jaamme tämän koodin kenelle tahansa uudelle Python-kehittäjälle lisäämättä dokumenttimerkkijonoja, hänen on jotenkin vaikea tietää tämän koodin toimintaa ja tarkoitusta. Hänen on ensin etsittävä käyttämiämme toimintoja. Mutta jos lisäämme koodiin dokumenttimerkkijonon, muiden kehittäjien on helppo ymmärtää koodi ilman lisätietoa toiminnoista. Emme rajoitu kommentoimaan tiettyjä rajoja; kommentit voivat olla yhden tai useamman rivin pituisia. Se voidaan myös lisätä useammin kuin kerran koodiin. Tuo sitten NumPy nimellä np.
'''Luo muuttuja, jolle välitetään 1x6-kokoinen matriisi'''joukko = esim. joukko ( [ yksitoista , 22 , 33 , 44 , 55 , 66 ] )
''''määritetään taulukko tofile()-funktiolle, jotta se voidaan tallentaa tiedostoon nimeltä arr'''
joukko . arkistoida ( 'arr.bin' )
'''näytä tiedosto fromfile-toiminnolla'''
Tulosta ( esim. tiedostosta ( 'arr.bin' , dtype = int ) )
Kuten seuraavassa pätkässä näkyy, dokumenttimerkkijonoja ei näytetä lähdössä, mikä tarkoittaa, että se ei vaikuta koodin ulostuloon tai kokoamiseen. Dokumenttimerkkijonot jätetään huomioimatta käännösprosessin aikana.
Johtopäätös
Tässä oppaassa opimme NumPyn dokumenttimerkkijonoista. Vertasimme asiakirjoja kommentteihin ja selitimme eron niiden välillä. Opimme dokumenttimerkkijonojen syntaksin ja kuinka kirjoitamme asiakirjat koodiimme. Lisäksi yritimme myös selittää esimerkkien avulla, mitä NumPyn docstringit ovat ja miten ne toimivat. Lopuksi huomautimme, että ne ovat välttämättömiä koodaajille. Emme toista NumPyn dokumenttimerkkijonojen merkitystä. Sanomme vain, että sinun tulee käyttää koodissasi olevia asiakirjoja. NumPyssa docstringien kirjoitustyyli on suosituin. Sitä käytetään laajasti ohjelmointiyhteisössä kertomaan toisilleen koodiensa toiminnasta ja toimivuudesta. Tämä opas auttaa sinua pääsemään alkuun NumPy-dokumenttien kanssa. Yritimme kattaa suurimman osan siitä, mitä tarvitset NumPyn dokumenttimerkkijonojen avulla.