Utilizzando l’utility appledoc è possibile generare automaticamente la documentazione delle classi ObjectiveC direttamente da Xcode durante la build del progetto.
Installare appledoc
La prima cosa da fare è installare appledoc. Il modo migliore è clonare i sorgenti del progetto pubblicati su GitHub in XCode e compilarli, così come riportato dalla sezione Quick Install del readme di progetto oppure dal paragrafo “Installing appledoc” dell’articolo Providing Custom Documentation in Xcode.
Una volta verificato che appledoc sia installato lanciando da terminale il comando appledoc –help, possiamo procedere alla configurazione del progetto Xcode per il quale si intende generare la documentazione.
Configurazione della build del progetto Xcode
Ogni progetto Xcode per il quale si desidera produrre la documentazione, dovrà essere configurato in modo da aggiungere delle fasi di build che si occuperanno di lanciare lo script appledoc che genera la documentazione.
Questi sono i passi di configurazione da seguire:
- aprire il progetto in Xcode e selezionarlo nel Project Navigator;
- creare un nuovo Target usando il tasto Add Target in basso a sinistra nella parte centrale della finestra;
- Xcode ci propone diverse tipologie di Target, la tipologia di Target che permette di eseguire degli script è Aggregate; scegliere quella relativa alla piattaforma del progetto (iOS o Mac OS X);
- nel nuovo Target selezionare il tab Build Phases e aggiungere una nuova Build Phase di tipo Run Script usando il tasto Add Build Phase in basso a destra della parte centrale della finestra;
- espandere la sezione Run Script appena creata ed inserire nel campo contraddistinto dal numero 1 lo script per generare la documentazione:
/usr/bin/appledoc \
–project-name “Project Name” \
–project-company “Company Name” \
–company-id com.company.id \
–logformat xcode \
–create-html \
–keep-undocumented-objects \
–keep-undocumented-members \
–exit-threshold 2 \
–ignore .m \
–ignore UnitTest \
“/Path/To/Project/Folder“dove sostituire:
Project Name con il nome del progetto
Company Name con il nome dell’autore/azienda
com.company.id con il dominio univoco (in stile java package) dell’autore/azienda
/Path/To/Project/Folder con il path completo al folder di progetto
- se si desidera avere una copia della documentazione in una cartella diversa da quella di default (/User_home_folder/Library/Developer/Shared/Documentation/DocSets/com.company.id.Project-Name.docset), creare una nuova Build Phase di tipo Run Script ed inserire al suo interno il seguente script:
cp -R /User_home_folder/Library/Developer/Shared/Documentation/DocSets/com.company.id.Project-Name.docset “/Destination/Path”
dove sostituire:
User_home_folder con la directory home dell’utente
com.company.id con il nome dominio univoco usato nello script precedente
Project-Name con il nome del progetto specificato nello script precedente, sostituendo con un trattino gli eventuali spazi.
Inserire i commenti nei sorgenti
Affinché la documentazione generata con dei contenuti, è necessario inserire all’interno dei degli header delle classi, e per tutti gli elementi che si vogliono documentare (classe, proprietà, metodi), dei commenti che rispettino la sintassi di appledoc che è molto simile a quella adottata da javadoc.
Questo è un esempio di commento per un metodo:
/**
* Create and returns the singleton instance.
*
* @param dataFile The data file name
* @return The singleton instance
* @exception NSException Raised when the singleton creation fails.
*/
Una guida completa alla sintassi di appledoc è riportata dalla documentazione presente sul sito del progetto.
Conclusioni
Ecco un esempio di quello che si otterrà per le proprie classi una volta generata la documentazione.
La documentazione generata da appledoc verrà visualizzata automaticamente in Xcode sia nel Quick Help inspector che nella sezione Documentation dell’Organizer.
Riferimenti
- Infinite Blog – Providing Custom Documentation in Xcode
- Gentle Bytes – Appledoc
Mi piace:
Mi piace Caricamento...
Zooid, il figlio di HAL 