จัดทำเอกสาร API สำหรับทั้งสองทีม

นักพัฒนาแอนดรอยด์และ iOS ต่างก็เรียกใช้โค้ดที่ใช้ร่วมกันของคุณ ดังนั้น เอกสารที่ชัดเจนจึงสำคัญไม่แพ้ตัวฟังก์ชันเอง 📝

KDocคือคอมเมนต์เอกสารของ Kotlin คุณเขียนไว้เหนือการประกาศโดยตรง แล้วเครื่องมือจะเปลี่ยนเป็นหน้าเอกสารอ้างอิงที่อ่านง่าย

โค้ดแสดงให้เห็นว่าเกิดอะไรขึ้น ส่วนเอกสารที่ดีอธิบาย เหตุผลและวิธีใช้งานที่ตั้งใจไว้ ระบุสิ่งที่ผู้เรียกควรคาดหวัง ไม่ใช่รายละเอียดการทำงานภายใน

ใช้แท็ก @param เพื่ออธิบายข้อมูลเข้าแต่ละรายการ ผู้เรียกใช้จากทั้งสองแอปจะรู้ว่าต้องส่งอะไรโดยไม่ต้องอ่านซอร์สโค้ด

แท็ก @return อธิบายสิ่งที่ส่งกลับมา คำอธิบายค่าที่คืนอย่างชัดเจนช่วยป้องกันความเข้าใจผิดเรื่องหน่วย ช่วงค่า หรือค่า null

ครอบชื่อด้วยวงเล็บเหลี่ยมเพื่อสร้าง ลิงก์ เช่น [Quote] ผู้อ่านจะไปยังชนิดข้อมูลที่เกี่ยวข้องในเอกสารที่สร้างขึ้นได้ทันที

ตัวอย่างสั้น ๆ มีประโยชน์มากกว่าคำอธิบายหลายย่อหน้า ตัวอย่างการเรียกใช้จริงเพียงส่วนเดียวก็ตอบคำถามส่วนใหญ่ได้ก่อนที่จะมีใครถาม

ทุ่มเทความพยายามให้กับ ส่วนเชื่อมต่อสาธารณะ ตัวช่วยภายในอาจมีคอมเมนต์เพียงเล็กน้อยได้ เพราะไม่มีทีมภายนอกเรียกใช้

นักพัฒนา Swift ก็อ่าน KDoc ของคุณเช่นกัน ดังนั้นให้อธิบายการทำงานด้วยภาษาธรรมดา หลีกเลี่ยงศัพท์เฉพาะของ JVM ที่ไม่มีความหมายสำหรับฝั่ง iOS

Dokkaอ่าน KDoc ของคุณและสร้างเว็บไซต์ที่เปิดดูได้ ทั้งสองทีมจึงมีเอกสารอ้างอิงร่วมกันชุดเดียว แทนการคาดเดาจากโค้ด

เอกสารที่ล้าสมัยทำให้เข้าใจผิดยิ่งกว่าไม่มีเอกสาร อัปเดต KDoc ในการเปลี่ยนแปลงเดียวกับโค้ด เพื่อไม่ให้ทั้งสองอย่างคลาดเคลื่อนจากกัน

เขียน KDoc ให้ส่วนเชื่อมต่อสาธารณะ อธิบายเหตุผล ระบุพารามิเตอร์และค่าที่คืน เพิ่มตัวอย่าง แล้วให้ Dokka แบ่งปันเอกสารกับทั้งสองทีม 🎉