Mendokumentasikan kod (pengenalan DocC)
Tulis komen DocC (/// dan /** ... */), dokumentasikan parameter/pulangan, tambah contoh, dan jana dokumentasi statik untuk pakej SwiftPM.
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)) // 5Dokumentasi 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) // 4Bahagian 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.
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
- Asas SwiftFormat / SwiftLint
- Panduan gaya, garis panduan reka bentuk API
- Mendokumentasikan kod (pengenalan DocC)