Aquesta pràctica consisteix en un primer contacte amb la documentació del SDK. Hi proposem:

• Fer-ne la instal·lació al nostre ordinador de manera que sigui fàcilment accessible i reconeixible per l'IDE que instal·larem a la següent pràctica.

• Veure'n les característiques i comprendre la necessitat que té el programador de consultar-la constantment.
  
  
• Relacionat amb el punt anterior, començar a comprendre en què consisteix un llenguatge de programació orientat a objectes (OOP), tal com és el llenguatge Java(TM) objecte del curs.

Per tal de portar a terme la pràctica, cal disposar de la documentació, comprimida a l'arxiu j2sdk-1_4_0-doc.zip, el qual és a la web del fabricant http://java.sun.com/. (29.8 Mb per aquesta versió)

• Comencem establint dos fets que convé tenir sempre al cap:
  
  
  • Java, com els llenguatges que li són pròxims (C i C++), té un conjunt relativament petit de paraules reservades. Algunes són comunes a C (for, while, break, int, etc.), inclosa la sintaxi, d'altres són pròpies de Java (try, catch, etc.), però en tot cas aquest conjunt és força reduït i fàcilment memoritzable.
    
    
  • Però Java és un llenguatge per a programació orientada a objectes (OOP). La programació orientada a objectes és un paradigma de programació ben diferent de la programació estructurada de C, Pascal...!
    
  
  
• La primera de les afirmacions del paràgraf anterior s'entén perfectament. La segona potser no. Classes, objectes... parlem-ne una miqueta:
  
  
  • Un objecte és una peça de programari que conté variables i mètodes per manipular aquestes variables,
    
    
    
    
    és a dir, un objecte conté dades, informació, i rutines per a tractar aquesta informació.
    
    Comparant-ho amb la programació estructurada, es tracta d'incloure en una mateixa entitat, l'objecte, variables i funcions (aquí les funcions es diuen mètodes) que poden actuar sobre aquestes variables.
    
    Un objecte ve a ser com les "estructures" del llenguatge C, amb l'afegitó que ara , a més, s'hi inclouen funcions (mètodes) per a manipular les dades que contenen.
    
    
  • Una aplicació Java consisteix en un conjunt d'objectes que s'interrelacionen entre ells mitjançant missatges:
    
    
    I els missatges no són altra cosa que crides a mètodes d'un cert objecte per tal que s'esdevingui alguna cosa...
    
    
  • Una classe és un prototipus que defineix les variables i els mètodes comuns a una certa mena d'objectes. Les classes venen a ser les matrius a partir de les quals, per derivació, extensió (la clàusula extends del llenguatge Java) o herència, (que tot vol dir el mateix), podrem crear diversos objectes de la mateixa mena. La classe defineix les variables i els mètodes comuns als objectes de certa mena, però després, cada objecte té els seus propis valors de les variables i cada mètode que s'executi serà el propi de l'objecte.
    
    
• Què és,doncs, tota aquesta documentació? L'API del SDK consisteix en un conjunt (enorme, segons estem veient!) de llibreries de classes ja predeterminades (són a la carpeta j2sdk1.4.0_01\lib) i aquesta documentació descriu les variables i els mètodes de cadascuna d'aquestes classes per tal que sapiguem què fan i com fer-les servir!
  
  Les nostres aplicacions Java consistiran en objectes derivats d'aquestes classes. Naturalment, un conjunt tan extens és impossible de memoritzar i, per tant, el programador ha der tenir a mà aquesta documentació perquè l'haurà de consultar molt i molt sovint.
  

Per tal de no predre'ns en aquest oceà d'informació, ara farem la documentació de la petita aplicació de la pràctica 1. Aquest n'era el codi:

• Ja es veu que tot allò que és entre /** i */ és un comentari que el compilador ignora. Per claredat, tal com està dins aquesta peça de codi,  els comentaris seran de color negre i el codi actiu serà  blau.
  
  A Java podem comentar a l'estil de C (/* ...comentari... */) i a l'estil de C++ (// ... comentari...), però si disposem les marques i etiquetes de comentari de manera adequada, llavors, l'executable javadoc.exe és capaç d'elaborar automàticament la documentació de la nostra classe!
  
  
• Observeu bé com està disposat el comentari al codi de la nostra classe: comença amb /** i acaba amb */ i cada línia va precedida per  * . Això serà reconegut per javadoc.exe i ho incorporarà a la documentació.
  
  
• Anem a documentar aquest fitxer font. Obriu la finestra de línia de comanaments del vostre sistema, situeu-vos a la carpeta c:\D110src, on ha d' ésser el fitxer ProvaFuncionament.java, i escriviu:
  
  

  c:\D110src>javadoc ProvaFuncionament.java

  
  Això executa el documentador javadoc.exe, el qual, a partir del fitxer font ProvaFuncionament.java, produeix un conjunt estructurat de documents HTML que són la documentació de la nostra aplicació. Aquest conjunt ha d'aparèixer a la mateixa carpeta en la qual estem treballant.
  
  
• Examinem els resultats: anem a la carpeta c:\D110src i obrim el fitxer index.html
  
  
  
  És clar que té el mateix aspecte de la documentació del SDK que hem instal·lat abans: evidentment, la documentació del SDK ha estat creada d'aquesta manera!.
  
  A l'apartat "All Classes", lluny de l'enorme quantitat d'abans, ara només n'hi ha una...