Nessuno si aspetterà mai che tu conosca tutti i tipi di dato o come utilizzare il framework SwiftUI dalla A alla Z. Primo perché sono troppi e secondo perché non ha molto senso occupare tutta quella memoria quando tutti gli oggetti si comportano e costruiscono allo stesso modo.

Ora, gli stessi limiti si impongono a me. Neanche io conosco tutto quello che c'è da sapere su Swift e SwiftUI. Proprio per questo quando lavoro o quando scrivo una nuova lezione faccio sempre riferimento alla documentazione ufficiale.

Padroneggiare la documentazione ufficiale di Xcode, Swift e SwiftUI è il primo passo verso il potersi liberare dal costante bisogno di trovare un tutorial o dal sentirsi impotenti quando si incontrano pezzi di codice inediti.

Ovviamente la parola documentazione fa venir la pelle d'oca a qualsiasi essere vivente.

Ti voglio assicurare già da adesso che non sarà come il manuale delle pentole. La documentazione ufficiale di Swift, SwiftUI etc è super intuitiva, accessibile direttamente da Xcode e sarà una manna dal cielo in molti dei problemi che affronterai.

Vediamo come usarla!

Se sei finito qui per caso, e vuoi imparare a creare app per dispositivi Apple, il corso SwiftUI tour è ciò che fa per te.

Come accedere alla documentazione di Xcode

La prima cosa da fare è sapere come accedere alla documentazione utilizzando la toolbar di Xcode.

Dalla toolbar principale seleziona Help. Qui trovi diverse voci, quelle che interessano a noi sono:

• Developer Documentation: Apre l'app che contiene la documentazione di tutti i framework disponibili.

• Swift programming language book. Apre il sito apple ufficiale sul linguaggio Swift.

Seleziona Developer Documentation. Dovrebbe comparire un'app simile a questa:

• Sulla sinistra trovi tutte voci della documentazione. Sono divise in base al framework o domain. Per esempio se cerchi SwiftUI troverai tutto l'essenziale riguardo Type e anche qualche tutorial.

• Nella barra superiore c'è un campo di ricerca che di solito userai per cercare Type o funzioni etc.

Quick Help

Un altro metodo veloce per accedere direttamente alla documentazione in base al codice che stai scrivendo è quello di utilizzare il Quick Help.

Il Quick help è un pannello interattivo che ti permette di esplorare il significato del codice ad hoc in base a cosa selezioni sull'Editor.

Il Quick Help si apre tenendo premuti Option ⌥ e passando il mouse/trackpad sopra una parola.
Le parole dovrebbero illuminarsi ed il background colorarsi di blu. Se fai un tap o click, si dovrebbe aprire un menu con la documentazione:

Dal menu, oltre ad una descrizione ed spesso degli esempi, troverai un link Open in Developer Documentation che ti porterà alla documentazione ufficiale:

Prima di capire come interpretare la documentazione, vediamo un altro sistema per aprire la documentazione dentro Xcode.

Inspector

Un altro modo per accedere alla documentazione è quello di utilizzare il pannello Inspector di Xcode. Se non ti ricordi come ci si accede, trovi gli step in questa lezione.

Passa il cursore dell'Editor su una parola, apri l'Inspector e seleziona il terzo pannello in alto a destra chiamato Quick Help:

Anche in questo caso, troviamo lo stesso contenuto mostrato nel Quick Help e se passi il cursore su altre parole il contenuto del pannello cambierà di conseguenza:

Navigare la documentazione

Il primo step nell'interpretare la documentazione è quello di capire come navigarla.

Breadcrumb

Apri la documentazione sul type Int e soffermiamoci sulla breadcrumb:

La breadcrumb ti permette di navigare orizzontalmente all'interno della libreria che contiene il Type che stai ispezionando.

Se analizziamo la breadcrumb di Int vediamo che questo type fa parte della categoria Numbers and Basic Values. Da lì, per esempio, puoi accedere alla documentazione degli altri type del framework Foundation come Double, Bool etc:

La stessa navigazione la trovi nel Navigator:

Se la parola type e oggetto ti suonano come nuovi, ho spiegato la differenza in questa lezione.

Leggere la documentazione

In base alla tipologia di elemento che stai ispezionando la documentazione cambia di contenuto e struttura.

Per il momento, analizziamo la documentazione di un type come Int o Text. Questi, genere hanno la seguente struttura:

1. Definizione, nome e compatibilità:

   1. Capiremo più avanti che esistono Type di natura differente: Structure, Class, Protocol etc. La tipologia di struttura sintattica usata nel definire il Type la trovi nella parte superiore e precede il nome del type. Nel nostro caso Int è una Structure.

   2. Compatibilità: Dopo il nome ed una breve descrizione trovi la lista di compatibilità. Utile quando vuoi utilizzare tecnologie nuove e ti serve sapere se sarà compatibile con la versione di sistema operativo supportata dalla tua app.

2. Topics: Una descrizione più o meno dettagliata del Type, seguita dalla lista di init, func, var, let e static var/let che potrai utilizzare sul quel type o gli oggetti di quel type. Ogni voce è un link ad una documentazione specifica:

3. Relationship: Infine, se scendi in fondo alla lista vedrai una lista di relazioni con altri type. Capiremo più in là che un Type può ereditare delle caratteristiche da altri type come protocol o class.
   Un'esempio lo abbiamo già incontrato nella lezione precedente quando abbiamo visto che Text ha un costruttore che accetta oggetti di type StringProtocol e ti avevo detto che String faceva parte di StringProtocol.
   Ed infatti, se entri nella documentazione di String e scendi in fondo, vedrai questa relationship tra i due:

Conclusione

Da qui in avanti prova ad aprire il Quick Help ogni qualvolta incontrerai un nuovo type o funzione fino a quel momento sconosciuta.

Vedrai che pur facendo del mio meglio per spiegarti un Type etc, la documentazione ti offrirà dei dettagli e casi particolari che prima o poi nel corso della tua carriera ti ritorneranno utili in determinati problemi.

Nella prossima lezione torneremo a scrivere codice e impareremo due nuove parole della grammatica del linguaggio Swift che già hai incontrato ed usato inconsapevolmente: var e let.

Per qualsiasi problema, al solito, scrivimi un commento qui o sui social.

Buona programmazione!