Swift Academy · Pelajaran

Mendokumentasikan kod (pengenalan DocC)

Tulis komen DocC (/// dan /** ... */), dokumentasikan parameter/pulangan, tambah contoh, dan jana dokumentasi statik untuk pakej SwiftPM.

Pelajaran 3 daripada 38 langkah

Mendokumentasikan kod (pengenalan DocC) ialah pelajaran Swift Academy percuma di CoddyKit. Ini ialah pelajaran 3 daripada 3. Sebanyak 3 pelajaran dalam laluan pembelajaran ini boleh dibaca sepenuhnya secara percuma — selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan praktikal dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran Swift Academy, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus Swift Academy merangkumi sejumlah 3 pelajaran.

Mengapa DocC?

DocC menukar komen yang diletakkan dengan baik kepada tapak dokumentasi yang boleh dilayari.

  • Gunakan /// atau /** ... */
  • Terangkan perkara yang dilakukan dan tunjukkan contoh kecil
  • Dokumentasikan parameter dan nilai pulangan

Dokumentasi fungsi

Letakkan /// terus di atas pengisytiharan. Gunakan senarai untuk Parameter dan Nilai pulangan.

/// Adds two integers and returns the sum.
/// - Parameters:
///   - a: First addend.
///   - b: Second addend.
/// - Returns: The sum of `a` and `b`.
/// - Remark: Pure function; no side effects.
func sum(_ a: Int, _ b: Int) -> Int { a + b }

print(sum(2, 3)) // 5

Dokumentasi jenis dan ahli

Komen blok /** ... */ sesuai digunakan untuk jenis; tambahkan dokumentasi ahli yang ringkas dengan ///.

/** A simple counter that tracks a running total.

 Use <code>increment()</code> to add one or a custom amount.
 
 - Note: The type is value-based (a struct).
 */
struct Counter {
    /// Current value of the counter.
    private(set) var value: Int = 0

    /// Increments the counter.
    /// - Parameter amount: How much to add (default is 1).
    mutating func increment(by amount: Int = 1) { value += amount }
}

var c = Counter()
c.increment()
c.increment(by: 3)
print("value =", c.value) // 4

Bahagian contoh

Gunakan bahagian Contoh yang kecil. Pastikan sampel ringkas untuk skrin mudah alih.

/// Repeats a message a given number of times.
///
/// **Example**
/// ```swift
/// repeatMessage("Hi", times: 2) // prints twice
/// ```
/// - Parameters:
///   - text: Message to print.
///   - times: How many times to print.
func repeatMessage(_ text: String, times: Int) {
    for _ in 0..<times { print(text) }
}

repeatMessage("Hi", times: 2)

Bina dokumentasi

Gunakan SwiftPM atau Xcode untuk membina dokumentasi. Utamakan dokumentasi sebaris supaya sentiasa dikemas kini.

// Generate documentation for a SwiftPM package (examples):
//   swift package generate-documentation --target MyLib
//   swift package generate-documentation --target MyLib --output-path Docs
//
// Preview in Xcode (DocC):
//   Product > Build Documentation
//
// Tip: keep docs close to code; DocC picks up symbols with /// or /** ... */.

Gaya dokumentasi

Petua:

  • Mulakan dengan ringkasan satu baris.
  • Terangkan perkara yang dilakukan, bukan butiran dalaman.
  • Dokumentasikan kes pinggir hanya jika penting.
  • Utamakan contoh kecil berbanding huraian panjang.

Bentuk komen DocC

Semakan pantas: Komen yang manakah menghasilkan dokumentasi DocC?

Imbas kembali

Imbas kembali: Tulis komen DocC di atas simbol, sertakan Parameter dan Nilai pulangan, tambahkan contoh kecil, kemudian jana dokumentasi melalui SwiftPM atau Xcode.

Percuma untuk bermula

Pelajari Swift dengan tutor kecerdasan buatan — percuma

Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.

Kursus
122
Pelajaran
409

Soalan Lazim

Adakah pelajaran “Mendokumentasikan kod (pengenalan DocC)” percuma?

Ya — sebanyak 3 pelajaran dalam laluan pembelajaran Swift Academy, termasuk “Mendokumentasikan kod (pengenalan DocC)”, boleh dibaca sepenuhnya secara percuma di web ini. Selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan interaktif dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Kursus Swift Academy merangkumi sejumlah 3 pelajaran.

Apakah yang akan saya pelajari dalam “Mendokumentasikan kod (pengenalan DocC)”?

Tulis komen DocC (/// dan /** ... */), dokumentasikan parameter/pulangan, tambah contoh, dan jana dokumentasi statik untuk pakej SwiftPM. Anda berlatih Swift Academy menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.

Adakah saya memerlukan pengalaman untuk memulakan Swift Academy?

Tiada pengalaman terdahulu diperlukan. Pembelajaran Swift Academy di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 3 daripada 3.

Berapa lamakah pelajaran “Mendokumentasikan kod (pengenalan DocC)” diambil?

Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.

Bolehkah saya menulis dan menjalankan kod dalam pelajaran Swift Academy ini?

Ya. Setiap pelajaran Swift Academy menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.

Semua pelajaran dalam kursus ini

  1. Asas SwiftFormat / SwiftLint
  2. Panduan gaya, garis panduan reka bentuk API
  3. Mendokumentasikan kod (pengenalan DocC)
← Kembali ke Swift Academy