DOM-rajapinnan toteuttaminen

Osa 1: Web API:n perusasetukset

1. Lue relevantti spesifikaatio.
2. Lisää .webidl-tiedosto(t) tähän hakemistoon jokaiselle toteutettavalle rajapinnalle. Jos tiedosto on jo olemassa, lisää siihen puuttuvat osat.
3. Jokaiselle rajapinnalle tämä luo traitin nimeltä {interface_name}Methods, johon pääsee käsiksi komennolla use crate::dom::bindings::codegen::Bindings::{interface_name}Binding.
4. Käytä traitia:
   • Lisäämällä vastaavan structin #[dom_struct]-attribuutilla
   • Lisäämällä metodeja, joiden runko on todo!.
5. Tässä vaiheessa structilla voi olla vain yksi jäsen: reflector_: Reflector,
   • Struct pitää dokumentoida linkillä sen rajapintaan spesifikaatiossa,
   • Trait-metodit pitää dokumentoida linkillä niiden määritelmiin rajapinnassa.
   • Esimerkkitulos.
6. Palaa spesifikaatioon,
   • etsi structillesi lisäjäseniä.
   • Näitä kutsutaan yleensä „internal sloteiksi” (esimerkki), tai joksikin, mikä on „associated” rajapinnan kanssa (esimerkki).
7. Lue DOM-rajapinnat.
8. Käyttäen oppimaasi, jokaiselle rajapinnan internal slotille:
   • Lisää sopiva jäsen kohdassa 4 lisättyihin structeihin.
   • Jos tämä vaatii muiden structien tai enumien määrittelyä, niiden pitää derivoida JSTraceable ja MallocSizeOf (esimerkki).
   • Kaikki yllä lisätyt JSTraceable-structit, jotka sisältävät jäseniä, jotka täytyy rootata koska ne ovat joko JS-arvoja tai DOM-objekteja, pitää merkitä #[cfg_attr(crown, crown::unrooted_must_root_lint::must_root)]. Esimerkki, jossa lintti tarvitaan JSVal-jäsenen vuoksi.
   • Jos tällainen struct assignataan muuttujaan, tee impl js::gc::Rootable structille ja käytä rooted! rootataksesi muuttujan (esimerkki).
   • Kaikki tämä voidaan muuttaa myöhemmin, joten käytä parasta arvostelukykyäsi tässä vaiheessa.
   • Lisää metodeja rakentamiseen (älä sekoita Web API:n osana olevaa Constructor-metodia).
   • Esimerkkitulos.

Osa 2: Ensimmäisen luonnoksen kirjoittaminen

1. Jokaiselle osan 1 kohdassa 3 mainitun bindings-traitin metodille:
   • Yleensä seuraa spesifikaation rakennetta: jos metodi kutsuu toista nimettyä algoritmia, toteuta se erillisenä structin yksityisenä metodina, jota trait-metodi kutsuu. Jos myöhemmin huomaat, että tätä yksityistä metodia voi käyttää muista structeista, tee siitä pub(crate).
   • Jokaiselle spesifikaation algoritmivaiheelle:
     • Kopioi rivi spesifikaatiosta.
     • Toteuta spesifikaatio koodissa (voi vaatia useamman rivin ja lisäkommentteja).
2. Huom: tietyt asiat tarvitaan usein algoritmin osana:
   • JSContext tai CurrentRealm, jotka ovat toisensa poissulkevia, saadaan generoidun trait-metodin argumenttina tämän konfiguraatiotiedoston avulla
   • GlobalScope: saadaan self.global()-kutsulla dom_struct-structilla tai GlobalScope::from_current_realm-kutsulla
   • On parasta hakea ne mahdollisimman aikaisin, esimerkiksi trait-metodin toteutuksen alussa, ja välittää ne alaspäin ref:inä (useimmissa tapauksissa JSContext/CurrentRealm täytyy olla &mut-viitteen takana)
   • On suositeltavaa, että JSContext/CurrentRealm on ensimmäinen argumentti, sen jälkeen &GlobalScope tarvittaessa, ja muut tarvittavat argumentit perässä
3. Tämän pitäisi antaa täydellinen ensimmäinen luonnos.

Osa 3: Testien ajaminen ja bugien korjaaminen

1. Nyt on aika tunnistaa, mitä WPT-testiä ajetaan ensimmäistä luonnosta vasten. Löydät ne täältä.
   • Tämä voi vaatia niiden ottamista käyttöön tällä konfiguraatiolla.
2. Testi voi epäonnistua, koska:
   • Koodissa on bugi. Nämä pitää korjata.
   • Testi käyttää muita API:ja, joita ei vielä tueta (yleensä ERROR).
3. Bugit pitää korjata. Copilotista on tässä vähän hyötyä.
4. Odotetut epäonnistumiset voidaan merkitä sellaisiksi tässä kuvatussa prosessissa.
5. Tämä osa on valmis, kun odottamattomia testituloksia ei enää ole.
6. Joskus reviewaajan neuvosta voit tehdä issuen ja kuvata epäonnistumisen, jota et voi korjata, merkitä testin epäonnistumiseksi ja jättää sen seuraavaan työvaiheeseen.

Osa 4: Refaktorointi ja lopullisen reviewn pyytäminen

1. Voit pyytää reviewa milloin tahansa, jos olet jumissa, mutta nyt on aika katsoa koodia viimeisen kerran ja päättää, haluatko refaktoroida jotain.
2. Jos olet tyytyväinen, nyt on aika pyytää lopullinen review.
3. Onnittelut, toteuttamasi uusi Web API pitäisi pian yhdistää.