{"id":417,"date":"2011-11-05T08:23:55","date_gmt":"2011-11-05T06:23:55","guid":{"rendered":"http:\/\/www.kristiansborg.dk\/bibliotek\/?page_id=417"},"modified":"2011-11-05T08:27:19","modified_gmt":"2011-11-05T06:27:19","slug":"kapitel-10-dokumentation-af-kode","status":"publish","type":"page","link":"https:\/\/www.kristiansborg.dk\/bibliotek\/b%c3%b8ger\/avanceret-java-programmering\/kapitel-10-dokumentation-af-kode\/","title":{"rendered":"Kapitel 10 Dokumentation af kode"},"content":{"rendered":"

Kode skrevet i et objektorienteret programmeringssprog som Java er let at genbruge. Man kan blot tage klassefilerne fra et projekt og bruge dem direkte i et andet uden at beh\u00f8ve rekompilering. Denne tidsbesparelse kan v\u00e6re mange penge v\u00e6rd p\u00e5 store projekter. Det eneste problem ved denne fremgangsm\u00e5de er, at det kan v\u00e6re sv\u00e6rt at huske, hvordan koden virker. Det kan godt v\u00e6re, at man kan se, at en funktion tager tre tekststrenge som parametre, men hvad hj\u00e6lper det, hvis man ikke aner, hvad de betyder? Problemet er endnu st\u00f8rre, hvis man udvikler frameworks, der skal s\u00e6lges til tredjepart, der slet ikke har noget kendskab til klasserne og deres metoder.<\/p>\n

\nDu l\u00e6ser en gammel bog<\/b>
\nDen bog, du l\u00e6ser her, er fra 1998, og mange ting kan have \u00e6ndret sig siden da.
\nVi h\u00e5ber, at du stadig kan finde relevant information i den.
\nHvis du vil l\u00e6se aktuelle oplysninger om de avancerede dele af Java, anbefaler vi
\nbogen Core Java – Advanced Features<\/a>\n<\/div>\n

Der er s\u00e5ledes brug for en m\u00e5de at dokumentere koden p\u00e5. Det, der er behov for, er en beskrivelse af pakker, klasser og metoder. For hver metode er det endvidere \u00f8nskeligt, at parametrene er beskrevet.<\/p>\n

 <\/p>\n

Med Java Development Kit f\u00f8lger et program, der kan oprette den slags dokumentation. Det hedder JavaDoc og arbejder ved at l\u00e6se kildeteksten igennem og kigge p\u00e5 de specielle JavaDoc-kommentarer, der kan inds\u00e6ttes. P\u00e5 baggrund af disse oprettes en r\u00e6kke HTML-dokumenter, der indeholder beskrivelser af klasserne og deres metoder. Dokumenterne indeholder ogs\u00e5 henvisninger til superklasser.<\/p>\n

 <\/p>\n

JavaDoc er blandt andet brugt til at generere den beskrivelse af samtlige Java-pakker, der findes p\u00e5 JavaSofts hjemmeside.<\/p>\n

 <\/p>\n

\"\"<\/a><\/p>\n

Figur 10-1: Sun bruger selv JavaDoc til at dokumentere kode.<\/p>\n

 <\/p>\n

 <\/p>\n

 <\/p>\n

 <\/p>\n

 <\/p>\n

 <\/p>\n

 <\/p>\n

 <\/p>\n

 <\/p>\n

 <\/p>\n

 <\/p>\n

 <\/p>\n

 <\/p>\n

 <\/p>\n

 <\/p>\n

I dette kapitel beskrives, hvordan JavaDoc bruges, og hvordan JavaDoc-kommentarer inds\u00e6ttes i kildeteksten.<\/p>\n

Mulighederne i JavaDoc<\/h1>\n

JavaDoc giver mulighed for at h\u00e5ndtere f\u00f8lgende dokumentation:<\/p>\n

 <\/p>\n

    \n
  • Angivelse af klasser og interfaces programm\u00f8rer<\/li>\n
  • Angivelse af klasser og interfaces versionsnumre<\/li>\n
  • Beskrivelse af pakker<\/li>\n
  • Beskrivelse af klasser<\/li>\n
  • Beskrivelse af metoder<\/li>\n
  • Beskrivelse af metoders parametre<\/li>\n
  • Beskrivelse af metoders returv\u00e6rdi<\/li>\n
  • Beskrivelse af metoders exceptions<\/li>\n
  • Henvisning til andre metoder og\/eller klasser<\/li>\n
  • Angivelse af, at en metode eller klasse er for\u00e6ldet.<\/li>\n
  • <\/li>\n<\/ul>\n

     <\/p>\n

     <\/p>\n

    Angivelse af dokumentation i kildeteksten<\/h1>\n

     <\/p>\n

    Som n\u00e6vnt tidligere skal den dokumentation, JavaDoc skal arbejde p\u00e5, angives i kildeteksten. Det g\u00f8res ved hj\u00e6lp af bestemte kommandoer. Alle kommandoerne skal skrives i kommentarer, s\u00e5 de ikke forstyrrer den rigtige Java-kode. I mods\u00e6tning til almindelige kommentarer, der indledes med \/*, indledes JavaDoc-kommentarer med \/**. De afsluttes ligesom almindelige kommentarer med *\/. Nedenst\u00e5ende eksempel viser, hvordan man kan beskrive en metode i kildeteksten:<\/p>\n

     <\/p>\n

    public class Test<\/p>\n

    {<\/p>\n

     <\/p>\n

    \/**<\/p>\n

    * Beskrivelse af en metode<\/p>\n

    *\/<\/p>\n

     <\/p>\n

    public void run()<\/p>\n

    {<\/p>\n

    }<\/p>\n

    }<\/p>\n

     <\/p>\n

    Bem\u00e6rk, at alle linier i JavaDoc-kommentarer indledes med en stjerne. Den tekst, der bare skrives i JavaDoc-kommentaren, vil altid blive regnet for at v\u00e6re beskrivelse af den n\u00e6ste metode. For at angive andre oplysninger, skal man bruge de specielle JavaDoc-parametre. F\u00e6lles for alle parametrene, der ogs\u00e5 skrives i JavaDoc-kommentarer, er, at de indledes med @. Der findes f\u00f8lgende JavaDoc-parametre:<\/p>\n

     <\/p>\n

     <\/p>\n

      \n
    • @author
      \nNavnet p\u00e5 den eller de programm\u00f8rer, der har skrevet klassen.<\/li>\n
    • @version
      \nKlassens versionsnummer og eventuelt dato.<\/li>\n
    • @param
      \nBeskrivelse af en af parametrene i en metode.<\/li>\n
    • @return
      \nBeskrivelse af en metodes returv\u00e6rdi.<\/li>\n
    • @exception
      \nBeskrivelse af den eller de exceptions, der kan opst\u00e5 ved at bruge metoden.<\/li>\n
    • @see
      \nHenvisning til en anden metode eller klasse.<\/li>\n
    • @since
      \nDen version af produktet, metoden f\u00f8rst optr\u00e5dte i.<\/li>\n
    • @deprecated
      \nAngivelse af at en metode er for\u00e6ldet, samt eventuelt hvilken metode, der skal bruges i stedet.<\/li>\n<\/ul>\n

      Hvis klassens forfatter er ukendt, b\u00f8r den angives som unascribed. Det vil sige:<\/p>\n

      \/**<\/p>\n

      * @author unascribed<\/p>\n

      *\/<\/p>\n

      @deprecated bruges, n\u00e5r en metode er blevet for\u00e6ldet og erstattet af en nyere. Den besked, der skrives efter @deprecated, skal beskrive hvorfor funktionen er for\u00e6ldet, samt hvilken funktion man b\u00f8r bruge i stedet. @deprecated b\u00f8r efterf\u00f8lges af en @see, der angiver navnet p\u00e5 den nye metode.<\/p>\n

      \/**<\/p>\n

      * Starter udf\u00f8rslen af programmet<\/p>\n

      *<\/p>\n

      * @deprecated\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Denne funktion er ALT for langsom. Brug i stedet runMe()<\/p>\n

      * @see\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 #runMe()<\/p>\n

      *\/<\/p>\n

      Hvis metoden ikke l\u00e6ngere er n\u00f8dvendig og derfor ikke er erstattet af en anden funktion, b\u00f8r @deprecated efterf\u00f8lges af No replacement. Der skal i s\u00e5 fald ikke v\u00e6re henvisninger til andre funktioner:<\/p>\n

       <\/p>\n

      \/**<\/p>\n

      * Starter udf\u00f8rslen af programmet<\/p>\n

      *<\/p>\n

      * @deprecated\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 No replacement<\/p>\n

      *\/<\/p>\n

       <\/p>\n

      Ved hj\u00e6lp af @see-parametren er det muligt at lave henvisninger b\u00e5de til klasser og til metoder. Det generelle format for @see er<\/p>\n

       <\/p>\n

      @see klasse#metode<\/p>\n

       <\/p>\n

       <\/p>\n

       <\/p>\n

      Hvis man vil lave en henvisning til en klasse, kan man n\u00f8jes med at skrive navnet p\u00e5 klassen. Vil man derimod lave en henvisning til en metode, skal b\u00e5de klasse og metodenavn skrives adskilt af en havel\u00e5ge (#). Henviser man til en metode i samme klasse som metoden selv, kan man n\u00f8jes med en havel\u00e5ge og funktionsnavnet. Man kan ogs\u00e5 lave en henvisning til en side, der ikke er genereret af JavaDoc. Det g\u00f8r man ved at skrive henvisningen som HTML-kode. Hvis man vil henvise til et dokument, der ikke findes online \u2013 for eksempel en bog \u2013 kan man g\u00f8re det, ved at angive navnet i anf\u00f8rselstegn. Nedenst\u00e5ende viser forskellige former for henvisninger:<\/p>\n

       <\/p>\n

      @see String<\/p>\n

      @see String#toString<\/p>\n

      @see #toString<\/p>\n

      @see <a href = \u201dhttp:\/\/www.javasoft.com\u201d>JavaSoft<\/a><\/p>\n

      @see \u201dAvanceret Java-programmering\u201d<\/p>\n

       <\/p>\n

      Med tiden forventes det, at @return bliver til @returns, og at @exception bliver til @throws. Dette er endnu ikke sket i Java Development Kit 1.2.<\/p>\n

      Organisering af JavaDoc-kommentarer<\/h2>\n

       <\/p>\n

      JavaDoc-kommentarer skal altid placeres f\u00f8r den del af programmet, de beskriver. Det vil sige, at kommentarer, der beskriver en klasse, skal placeres f\u00f8r definitionen af klassen, ligesom kommentarer, der beskriver en metode, skal placeres f\u00f8r definitionen af metoden.<\/p>\n

       <\/p>\n

      Parametrenes r\u00e6kkef\u00f8lge er heller ikke helt ligegyldig. Generelt b\u00f8r de placeres i samme r\u00e6kkef\u00f8lge, som de er blevet gennemg\u00e5et i dette kapitel. Hvis den samme parameter skal bruges flere gange med forskellige v\u00e6rdier, b\u00f8r f\u00f8lgende regler iagttages:<\/p>\n

       <\/p>\n

        \n
      • Ved flere programm\u00f8rer b\u00f8r programm\u00f8rerne angives i kronologisk orden. Det vil sige, at den programm\u00f8r, der oprettede klassen, st\u00e5r \u00f8verst.<\/li>\n
      • Ved flere parametre til en metode skal der oprettes en @param til hver. Parametrene angives i samme r\u00e6kkef\u00f8lge, som de st\u00e5r i metodens signatur.<\/li>\n
      • Hvis en metode kaster flere exceptions, angives disse med hver deres @exception i alfabetisk r\u00e6kkef\u00f8lge.<\/li>\n
      • Hvis der er flere henvisninger, angives disse med hver deres @see i alfabetisk orden.<\/li>\n<\/ul>\n

         <\/p>\n

        For at g\u00f8re JavaDoc-kommentaren mere overskuelig kan den opdeles i flere blokke. Der kan skabes afstand mellem to blokke i kommentaren ved at lave en linie, der kun indeholder en stjerne.<\/p>\n

        Brug af HTML-kode<\/h2>\n

        Da JavaDoc genererer HTML-dokumenter, kan man ogs\u00e5 bruge HTML-kommandoer i kommentarerne. De bruges pr\u00e6cis som man ville bruge dem i et almindeligt HTML-dokument. Man b\u00f8r dog undlade at bruge <H1> og <H2>, da de bliver brugt af JavaDoc. Til geng\u00e6ld kan man med fordel<\/p>\n

         <\/p>\n

        bruge <code>\u2026<\/code> til at omkranse kodeeksempler og <p> til at adskille afsnit i en beskrivelse:<\/p>\n

         <\/p>\n

        \/**<\/p>\n

        * Denne beskrivelse er temmelig lang<\/p>\n

        * .<\/p>\n

        * .<\/p>\n

        * <p><\/p>\n

        * Derfor er det rart, at den er delt i flere afsnit<\/p>\n

        *<\/p>\n

        *<\/p>\n

        *\/<\/p>\n

         <\/p>\n

        public class test<\/p>\n

        {<\/p>\n

        \u2026<\/p>\n

        }<\/p>\n

         <\/p>\n

        Brug af JavaDoc-programmet<\/h1>\n

         <\/p>\n

        N\u00e5r kildeteksten er dokumenteret, beh\u00f8ver man blot at bruge JavaDoc-programmet for at f\u00e5 genereret specifikationerne i HTML-format. JavaDoc-programmet ligger i bin-biblioteket i Java-installationen. Programmet har f\u00f8lgende syntaks:<\/p>\n

         <\/p>\n

        javadoc [-options] fil|pakke<\/p>\n

         <\/p>\n

        Som det ses, kan man v\u00e6lge at generere dokumentation for en enkelt fil eller for en hel pakke. For at give brugeren mulighed for f\u00e5 dokumentationen genereret pr\u00e6cis, som han vil have den, er det muligt at angive en r\u00e6kke options.<\/p>\n

         <\/p>\n

          \n
        • -public
          \nAngiver, at kun public klasser, metoder og attributter vises.
          \n-protected
          \nAngiver, at kun public eller protected klasser, metoder og attributter vises. Angives ingen options anvendes denne.
          \n-package
          \nAngiver, at kun pakker samt public eller protected klasser, metoder og attributter vises.
          \n-private
          \nAngiver, at alle klasser og alle metoder og attributter vises.
          \n-Jflag<\/em>
          \nOverf\u00f8rer flag <\/em>direkte til runtime-systemet.
          \n-encoding navn
          \n<\/em>Angiver den m\u00e5de, kildeteksterne er kodet p\u00e5.
          \n-docencoding navn<\/em>
          \n<\/em>Angiver den m\u00e5de, HTML-filerne skal kodes p\u00e5.
          \n-version
          \nAngiver, at @version-parametre skal medtages. Angives \u2013version ikke, bliver disse udeladt.<\/li>\n
        • <\/li>\n
        • -author
          \nAngiver, at @author-parametre skal medtages. Angives \u2013author ikke, bliver disse udeladt.
          \n-noindex
          \nAngiver, at der ikke skal oprettes en liste over pakker.
          \n-notree
          \nAngiver, at der ikke skal oprettes en oversigt over klasser og interfaces.
          \n-d bibliotek
          \n<\/em>Angiver det bibliotek, HTML-filerne skal gemmes i. Biblioteket kan angives som en absolut eller en relativ sti.
          \n-verbose
          \nAngiver, at JavaDoc-programmet skal generere mere output end s\u00e6dvanligt. Angives
          \n-verbose ikke, vises kun en besked pr. fil. Hvis \u2013verbose angives, bliver det derudover ogs\u00e5 vist, hvor mange millisekunder, der er blevet brugt p\u00e5 at behandle hver java-fil.
          \n-sourcepath sti<\/em>
          \nAngiver den sti, der skal s\u00f8ges efter java-filer i. Hvordan stien angives afh\u00e6nger af, om man angiver java-filer eller pakker som parameter. N\u00e5r man angiver pakker, skal sourcepath v\u00e6re stien til den pakke, der ligger \u00f8verst i hierakiet. Hvis man vil dokumentere en pakke, der hedder java.tree, der ligger i biblioteket
          \n\\prog\\java\\tree\\*.java
          \nskal sourcepath s\u00e6ttes til
          \n-sourcepath \\prog
          \nN\u00e5r der genereres dokumentation for enkelte klasser, skal sourcepath angive det bibliotek, java-filerne ligger i. Det vil alts\u00e5 sige, at hvis man vil have genereret dokumentation for filen
          \n\\prog\\java\\tree\\Tree.java
          \nskal sourcepath s\u00e6ttes til
          \n-sourcepath \\prog\\java\\tree
          \nDet er ikke n\u00f8dvendigt at angive en sourcepath, hvis man starter JavaDoc-programmet fra det bibliotek, man ville have angivet som sourcepath.
          \n-classpath sti
          \n<\/em>Som regel er det ikke n\u00f8dvendigt at bruge \u2013classpath. Hvis man vil angive placeringen af de java-filer, der skal dokumenteres, skal man bruge \u2013sourcepath i stedet (se ovenst\u00e5ende).
          \nStien angivet efter \u2013classpath, angiver placeringen af de klassefiler, JavaDoc-programmet skal bruge. Hvis \u2013sourcepath ikke er angivet, angiver stien ogs\u00e5 placeringen af de filer, der skal dokumenteres.
          \nAngives \u2013classpath ikke, s\u00e6ttes det til det aktuelle bibliotek plus de biblioteker, der r angives i CLASSPATH-variablen.
          \n-nodeprecated
          \nAngiver, at elementer markeret med @deprecated-parametren skal udelades.
          \noverview sti
          \n<\/em>L\u00e6ser oversigt over dokumentationen fra en HTML-fil.
          \nnodeprecatedlist
          \nAngiver, at der ikke skal oprettes en oversigt over elementer markeret med @deprecated-parametren.<\/li>\n
        • -linkall
          \nAngiver, at der skal oprettes henvisninger til klasser og pakker, selvom der ikke bliver genereret dokumentation for dem i denne omgang. Denne option g\u00f8r det muligt at generere en samlet dokumentation for flere projekter ad flere gange. Det g\u00f8r det ogs\u00e5 muligt at n\u00f8jes med at opdatere en del af dokumentationen, hvis man kun foretager \u00e6ndringer i nogle f\u00e5 klasser.<\/li>\n
        • <\/li>\n
        • -breakindex
          \nAngiver, at indeksfilen skal opdeles i flere filer. Hvis man genererer dokumentation for mange klasser, kan indeksfilen blive s\u00e5 stor, at den er tung at hente over Internet. I disse tilf\u00e6lde kan det anbefales, at bruge \u2013breakindex til oprette en indeksfil til hvert bogstav.<\/li>\n
        • -frame
          \nAngiver, at dokumentationen skal organiseres ved hj\u00e6lp af HTML-frames. Med denne option sat, bliver der oprettet en frame med en oversigt over samtlige pakker. Der bliver ogs\u00e5 oprettet en frame med en oversigt over de klasser, der findes i pakken, mens hovedparten af vinduet bruges til en beskrivelse af den aktuelle klasse.<\/li>\n
        • -nohelp
          \nAngiver, at der ikke skal oprettes et link til en hj\u00e6lpeside. Hj\u00e6lpesiden bliver ikke automatisk genereret af JavaDoc. Angives andet ikke med \u2013helpfile hedder hj\u00e6lpefilen help.html.<\/li>\n
        • -title html-kode
          \n<\/em>Angiver et stykke HTML-kode, der skal inds\u00e6ttes \u00f8verst p\u00e5 hver side.<\/li>\n
        • -footer html-kode
          \n<\/em>Angiver et stykke HTML-kode, der skal inds\u00e6ttes som bundtekst p\u00e5 hver side.<\/li>\n
        • -header html-kode<\/em>
          \nAngiver et stykke HTML-kode, der skal inds\u00e6ttes som toptekst p\u00e5 hver side.<\/li>\n
        • -bottom html-kode<\/em>
          \n<\/em>Angiver et stykke HTML-kode, der skal inds\u00e6ttes nederst p\u00e5 hver side.<\/li>\n
        • -helpfile fil<\/em>
          \n<\/em>Angiver navnet p\u00e5 den fil, der skal bruges som hj\u00e6lpefil. Angives intet navn anvendes help.html. Hvis der slet ikke skal laves en henvisning til en hj\u00e6lpefil, skal man bruge \u2013nohelp.<\/li>\n<\/ul>\n