Rajapintadokumentaation muodostaminen osittain automatisoidusti lähdekoodista
Melkinen, Miska (2019)
2019
Tietotekniikka
Informaatioteknologian ja viestinnän tiedekunta - Faculty of Information Technology and Communication Sciences
This publication is copyrighted. You may download, display and print it for Your own personal use. Commercial use is prohibited.
Hyväksymispäivämäärä
2019-05-20
Julkaisun pysyvä osoite on
https://urn.fi/URN:NBN:fi:tty-201905031469
https://urn.fi/URN:NBN:fi:tty-201905031469
Tiivistelmä
Ohjelmointirajapintojen dokumentaatio on tärkeässä osassa rajapintojen käytön oppimisessa ja oikeanlaisessa käytössä. Dokumentaation virheettömyys ja ajantasaisuus ovat tärkeitä elementtejä dokumentaation laadun kannalta. Rajapinnan dokumentaatio täytyy yleensä aina päivittää, kun rajapinnan totetutus päivittyy. Dokumentaation uudistaminen voi olla työlästä ja manuaalisesti dokumentoidessa voi syntyä helposti virheitä tai rajapintaan lisättyjen uusien ominaisuuksien dokumentaatiota ei välttämättä muisteta lisätä.
Muodostettaessa dokumentaatiopohja automaattisesti lähdekoodista voidaan varmistua siitä, että dokumentaatiosta löytyvien rakenteiden nimet, tyypit ja ominaisuudet vastaavat senhetkistä toteutusta. Dokumentaatiopohjan muodostaminen ei kuitenkaan poista ohjelmistokehittäjän vastuuta rakenteiden kuvauksien kirjoittamisesta dokumentaatioon, mutta vähentää manuaalisesti suoritettavan työn määrää dokumentoidessa.
Työssä suunniteltiin ja toteutettiin työkalu ohjelmointirajapintojen dokumentointiin. Toteutetun työkalun avulla pyrittiin helpottamaan dokumentointiprosessia sekä varmistamaan rajapinnan toteutuksen ja rajapinnan dokumentaation vastaavuus toisiinsa nähden. Rajapintadokumentointityökalu lukee rajapinnan lähdekoodia ja muodostaa rajapintaa kuvaavan tietomallin hyödyntäen lähdekoodia. Dokumentoitavan rajapinnan lähdekoodiin lisättiin attribuuttiluokkia, joilla voidaan kirjata lisätietoja dokumentaatiotyökalun jäsentäjälle. Muodostettua rajapinnan tietomallia voidaan muokata sekä tallentaa siihen kuvaustekstejä työkaluun toteutetun graafisen käyttöliittymän kautta.
Rajapintaa kuvaavan tietomallin muodostamisessa käytettiin .NET-kehyksen kääntäjään perustuvaa Roslyn-työkalua, jonka avulla voitiin tarkastella C#-ohjelmointikielellä kirjoitetusta lähdekoodista käätämisen jäsennysvaiheessa muodostettua syntaksipuuta. Dokumentoitavien rakenteiden tunnistamiseen syntaksipuusta käytettiin työssä suunniteltuja attribuuttiluokkia, joita oli lisätty dokumentoitavan eRA-järjestelmän koodiin. Attribuuttiluokkien avulla kirjattiin lähdekoodiin dokumentointia helpottavia lisätietoja, kuten rajapintaversionumeroita, metodien poikkeuksia ja metodien kutsumiseen vaadittavia esiehtoja. Tietomallista voidaan muodostaa toteutetulla dokumentointityökalulla LaTeX-muotoinen dokumentaatio.
Toteutetulla dokumentointityökalulla tuotettiin dokumentoitavaksi valitun Atostek eRA -järjestelmän integraatiorajapinnan uuden version dokumentaatio. Työkalun käyttäminen nopeutti dokumentaation muodostamista verrattuna edellisten dokumentaatioversioiden kirjoittamiseen. Toteutetun työkalun toimintaa testattiin tuottamalla jo olemassa oleva rajapintadokumentaatio uudestaan ja vertaamalla sitä manuaalisesti kirjoitettuun dokumentaation. Työkalun ansiosta havaittiin virheitä edellisissä dokumentaatioversiossa, joten työkalun käyttäminen paransi myös dokumentaation laatua.
Muodostettaessa dokumentaatiopohja automaattisesti lähdekoodista voidaan varmistua siitä, että dokumentaatiosta löytyvien rakenteiden nimet, tyypit ja ominaisuudet vastaavat senhetkistä toteutusta. Dokumentaatiopohjan muodostaminen ei kuitenkaan poista ohjelmistokehittäjän vastuuta rakenteiden kuvauksien kirjoittamisesta dokumentaatioon, mutta vähentää manuaalisesti suoritettavan työn määrää dokumentoidessa.
Työssä suunniteltiin ja toteutettiin työkalu ohjelmointirajapintojen dokumentointiin. Toteutetun työkalun avulla pyrittiin helpottamaan dokumentointiprosessia sekä varmistamaan rajapinnan toteutuksen ja rajapinnan dokumentaation vastaavuus toisiinsa nähden. Rajapintadokumentointityökalu lukee rajapinnan lähdekoodia ja muodostaa rajapintaa kuvaavan tietomallin hyödyntäen lähdekoodia. Dokumentoitavan rajapinnan lähdekoodiin lisättiin attribuuttiluokkia, joilla voidaan kirjata lisätietoja dokumentaatiotyökalun jäsentäjälle. Muodostettua rajapinnan tietomallia voidaan muokata sekä tallentaa siihen kuvaustekstejä työkaluun toteutetun graafisen käyttöliittymän kautta.
Rajapintaa kuvaavan tietomallin muodostamisessa käytettiin .NET-kehyksen kääntäjään perustuvaa Roslyn-työkalua, jonka avulla voitiin tarkastella C#-ohjelmointikielellä kirjoitetusta lähdekoodista käätämisen jäsennysvaiheessa muodostettua syntaksipuuta. Dokumentoitavien rakenteiden tunnistamiseen syntaksipuusta käytettiin työssä suunniteltuja attribuuttiluokkia, joita oli lisätty dokumentoitavan eRA-järjestelmän koodiin. Attribuuttiluokkien avulla kirjattiin lähdekoodiin dokumentointia helpottavia lisätietoja, kuten rajapintaversionumeroita, metodien poikkeuksia ja metodien kutsumiseen vaadittavia esiehtoja. Tietomallista voidaan muodostaa toteutetulla dokumentointityökalulla LaTeX-muotoinen dokumentaatio.
Toteutetulla dokumentointityökalulla tuotettiin dokumentoitavaksi valitun Atostek eRA -järjestelmän integraatiorajapinnan uuden version dokumentaatio. Työkalun käyttäminen nopeutti dokumentaation muodostamista verrattuna edellisten dokumentaatioversioiden kirjoittamiseen. Toteutetun työkalun toimintaa testattiin tuottamalla jo olemassa oleva rajapintadokumentaatio uudestaan ja vertaamalla sitä manuaalisesti kirjoitettuun dokumentaation. Työkalun ansiosta havaittiin virheitä edellisissä dokumentaatioversiossa, joten työkalun käyttäminen paransi myös dokumentaation laatua.