Documentare l'API per entrambi i team

Sia gli sviluppatori Android sia quelli iOS chiamano il codice condiviso, quindi una documentazione chiara è importante quanto le funzioni stesse. 📝

KDoc è il commento di documentazione di Kotlin. Lo scrive subito sopra una dichiarazione e gli strumenti lo trasformano in pagine di riferimento leggibili.

Il codice mostra che cosa accade; una buona documentazione spiega il perché e l’utilizzo previsto. Indichi ciò che il chiamante deve aspettarsi, non il funzionamento interno.

Usi il tag @param per descrivere ogni input. Chi chiama dalle due app saprà esattamente che cosa passare senza leggere il sorgente.

Il tag @return descrive ciò che viene restituito. Una nota chiara sul valore restituito evita supposizioni errate su unità, intervalli o valori null.

Racchiuda i nomi tra parentesi quadre per creare collegamenti, come [Quote]. I lettori passeranno direttamente ai tipi correlati nella documentazione generata.

Un piccolo esempio vale più di interi paragrafi. Un frammento che mostra una chiamata reale risponde alla maggior parte delle domande prima ancora che vengano poste.

Dedichi il suo impegno alla superficie public. Gli helper internal possono avere pochi commenti, poiché nessun team esterno li chiamerà.

Anche gli sviluppatori Swift leggono il suo KDoc, quindi descriva il comportamento con termini semplici. Eviti il gergo JVM che sul lato iOS non avrebbe significato.

Dokka legge il suo KDoc e produce un sito consultabile. Entrambi i team ottengono un unico riferimento condiviso, invece di dover indovinare dal codice.

Una documentazione obsoleta può fuorviare più dell’assenza di documentazione. Aggiorni il KDoc nella stessa modifica del codice, così i due elementi non divergeranno mai.

Scriva il KDoc sulla sua public API, spieghi il perché, documenti parametri e valori restituiti, aggiunga un esempio e lasci che Dokka lo condivida con entrambi i team. 🎉