Dokumentowanie API dla obu zespołów

Zarówno programiści Androida, jak i iOS wywołują Twój wspólny kod, dlatego przejrzysta dokumentacja jest równie ważna jak same funkcje. 📝

KDoc to komentarz dokumentacyjny Kotlina. Zapisuje się go bezpośrednio nad deklaracją, a narzędzia przekształcają go w czytelne strony referencyjne.

Kod pokazuje, co się dzieje, a dobra dokumentacja wyjaśnia dlaczego i jak należy używać danego elementu. Opisz, czego powinien spodziewać się wywołujący, a nie sposób działania wewnątrz.

Używaj tagu @param, aby opisać każde dane wejściowe. Wywołujący z obu aplikacji będą dokładnie wiedzieć, co przekazać, bez czytania kodu źródłowego.

Tag @return opisuje zwracaną wartość. Jasna informacja o wyniku zapobiega błędnym założeniom dotyczącym jednostek, zakresów lub wartości null.

Umieść nazwy w nawiasach kwadratowych, aby utworzyć odnośniki, na przykład [Quote]. Czytelnicy mogą wtedy przejść bezpośrednio do powiązanych typów w wygenerowanej dokumentacji.

Krótki przykład jest lepszy niż akapity opisu. Jeden fragment pokazujący rzeczywiste wywołanie odpowiada na większość pytań, zanim jeszcze zostaną zadane.

Skup wysiłek na publicznej powierzchni API. Wewnętrzne funkcje pomocnicze mogą mieć krótkie komentarze, ponieważ żaden zewnętrzny zespół nie będzie ich wywoływać.

Programiści Swift również czytają Twój KDoc, dlatego opisuj działanie prostymi słowami. Unikaj żargonu JVM, który nic nie znaczy po stronie iOS.

Dokka odczytuje KDoc i tworzy stronę, którą można przeglądać. Oba zespoły otrzymują jedną wspólną dokumentację zamiast zgadywać na podstawie kodu.

Nieaktualna dokumentacja wprowadza w błąd bardziej niż jej brak. Aktualizuj KDoc w ramach tej samej zmiany co kod, aby te elementy nigdy się nie rozjechały.

Dokumentuj publiczne API za pomocą KDoc, wyjaśniaj dlaczego, opisuj parametry i zwracane wartości, dodawaj przykład, a następnie pozwól, aby Dokka udostępniła dokumentację obu zespołom. 🎉