Questo sito utilizza i Cookie. Clicca su Accetto per consentirne l'utilizzo, altrimenti in Info trovi maggiori informazioni.

Javadoc per Applicazioni Android







 

Alle prese con l'applicazione Android che sto realizzando come progetto per un esame (e che sto pensando di rendere disponibile, quando pronta, anche su play store) mi sono scontrato con la creazione dei Javadoc "automatica" resa disponibile da Eclipse.

Andava tutto bene fino a quando non ho iniziato ad utilizzare le librerie private di Google per il supporto delle versioni precedenti...  I problemi riscontrati e per cui sto per proporvi una soluzione sono i seguenti:

  • Impossibilità di allegare la documentazione alle librerie di supporto fornite da Google e importate automaticamente, infatti per queste librerie si ha la voce javadoc non modificabile
  • Esportazione automatica della documentazione javadoc anche per le nostre classi quando queste usano le librerie di supporto private di Google

 

Prima di iniziare voglio sottolineare una cosa che ho letto in rete e per cui ho visto pareri discordanti... In un famoso forum un utente chiedeva se avesse dovuto commentare anche le parti di codice private o protected e, la prima risposta che gli è stata data era un secco e chiaro no. Andando avanti a leggere, ho trovato gente che invece consigliava vivamente di farlo e altri che non sapevano da che parte schierarsi.

Il mio consiglio è quello di commentare sempre e comunque tutto il codice, soprattutto le parti che potrebbero risultare ambigue. Io andrei anche oltre e consiglio di commentare anche le parti che al momento ci sembrano ovvie perchè tra qualche mese potrebbero non esserlo più!

Ovviamente senza essere tediosi, ma cercando di spiegare ogni passaggio importante del nostro codice comprese le parti private o protected, tanto poi, come vedremo dopo, è possibile scegliere il livello di protezione dei javadoc esportati!

 

Allegare la documentazione alla libreria android-support-v4.jar

Come dicevo prima, quando si cerca di visualizzare la documentazione (tramite F2 o soffermandosi sui metodi richiamati) delle librerie private di Google si può ottenere il seguente risultato:

 

 

no Javadoc Attached Image

 

 

Allora  si potrebbe pensare di utilizzare il comando File->Build path -> Libraries per collegare i Javadoc ed i file sorgente, ma ci accorgeremmo che queste voci, se le librerie sono state importate automaticamente dall'ADT (Android Development Tools), non sono modificabili e allora un modo per collegare la documentazione è quello di aggiungere un file denominato android-support-v4.jar.properties nella cartella libs del nostro progetto, dove abbiamo il file android-support-v4.jar. Nell'immagine seguente è indicato dove:

 

 

libsFolder

 

 

 

 

 

Ma cosa contiene questo file?! Nel file dovremo mettere semplicemente i percorsi relativi alla documentazione e ai sorgenti della libreria, ovvero ci scriveremo:

 

doc=[Percorso Base Andoird SDK]/android-sdk-linux/docs/reference
src=[Percorso Base Andoird SDK]/android-sdk-linux/extras/android/support/v4/src

 

Ovviamente queste righe sono scritte per me che utilizzo Ubuntu Linux, ma vanno bene anche per chi è utente MAC; in caso utilizziate Windows dovete solo invertire la direzione delle barre oblique.

Una volta fatto questo è sufficiente riavviare Eclipse e potremo vedere le indicazioni estratte dai javadoc ogni volta che ci soffermeremo su un metodo di queste librerie o che premeremo F2.

 

Esportazione dei javadoc


Utilizzando queste librerie nelle nostre classi potremmo avere un problema nella generazione automatica dei javadoc della nostra applicazione. Ma allora come fare quando abbiamo speso ore ed ore a documentare la nostra applicazione e non riusciamo a generare i javadoc ?!

 

Nessun problema, da Terminale (o da cmd per Windows) possiamo farlo in modo molto semplice. Ora scrivo questa guida per utenti di Linux, ma con qualche modifica dei vari percorsi, anche chi utilizza Windows può farcela!

 

Iniziamo con il raggiungere la cartella del nostro progetto:

 

cd workspace/android/ApplicazioneAndroid/

 

 ora diamo il seguente comando:

 

javadoc -private -d doc -sourcepath src/ -subpackages 
com.example.android.apps.packagePrincipaleNostraApplicazione

 

Con questo comando chiediamo di compilare i Javadoc fino al livello private, ovvero che comprendono anche i metodi, i costruttori, le variabili e quant'altro contrassegnati con private o protected. Volendo possiamo omettere il parametro -private per evitare che questi siano visibili nella documentazione esportata.

La documentazione sarà visibile all'interno del nostro progetto in una cartella denominata doc. Potremmo regolarci così e creare due diverse cartelle, una per la documentazione pubblica e una per quella privata ottenendo le due esportazioni una nella cartella privateDocs e l'altra nella cartella publicDocs con i relativi comandi:

 

javadoc -private -d privareDocs -sourcepath src/ -subpackages 
com.example.android.apps.packagePrincipaleNostraApplicazione

 

per quella privata e:

 

javadoc -d publicDocs -sourcepath src/ -subpackages 
com.example.android.apps.packagePrincipaleNostraApplicazione

 

 per quella pubblica.

 

 




Se ti è piaciuto questo articolo condividilo come preferisci, oppure lascia un commento!!

Parliamo di come si può essere sicuri che i rimedi si acquista on-line sono sicuri. Senza dubbio, uno dei luoghi emozionante, dove le persone possono acquistare farmaci è Internet. Ci sono farmaci variante per ogni malattie. Kamagra è un farmaco prescritto per il trattamento di diverse denunce. Cosa ne pensi "http://journal-info.net/buy/levitra-online.html "? Dove è possibile avere informazioni dettagliate su "buy levitra online "? Le questioni, come "buy levitra ", si riferiscono a vari tipi di problemi medici. Vivere con la disfunzione erettile può essere un vero problema. Ci sono farmaci variante per risolvere la disfunzione sessuale maschile. Il farmaco è per voi. Mai dare ad altre persone, anche se i loro reclami siano uguali ai suoi.