Komentar Dart

Bahasa Dart mendukung total 3 jenis komentar: komentar satu baris, komentar multibaris, komentar dokumentasi; kompiler akan mengabaikan teks biasa di dalam komentar, hanya komentar dokumentasi yang bisa digunakan untuk menghasilkan dokumentasi kode.

Tujuan komentar adalah memudahkan pengembang membaca kode serta memahami fungsi dan kegunaannya. Selain itu, komentar juga bisa digunakan untuk menonaktifkan sebagian kode sementara saat proses debug dan pencarian kesalahan program.

Komentar dokumentasi memungkinkan kita menggunakan alat khusus untuk menghasilkan dokumentasi bantuan API secara otomatis. Hal ini memudahkan kita mengecek fungsi kode sendiri maupun orang lain yang menggunakan kode kita.

Jika kamu pernah mempelajari bahasa pemrograman lain, kamu akan cepat memahami komentar Dart. Sintaksnya hampir sama dengan bahasa berbasis C seperti C, C++, Java, C#.

1. Komentar satu baris //

1. Dimulai dengan simbol //;
2. Semua teks dari // hingga akhir baris akan diabaikan oleh kompiler Dart;
3. Hanya berlaku untuk baris saat ini, tidak bisa digunakan lintas baris.

Contoh

void main() {
  // TODO: Refaktor menjadi pabrik abstrak sapaan llama?
  print('Selamat datang di peternakan llama saya!');
}
Code language: JavaScript (javascript)

2. Komentar multibaris /* */

1. Penanda awal /*, penanda akhir */;
2. Semua konten di antara /* dan */ akan diabaikan kompiler (kecuali komentar dokumentasi, lihat di bawah);
3. Mendukung penulisan bersarang.

Contoh

void main() {
  /*
   * Memelihara llama membutuhkan banyak tenaga, bisa pertimbangkan memelihara ayam.

  Llama larry = Llama();
  larry.feed();
  larry.exercise();
  larry.clean();
   */
}Code language: Dart (dart)

Pada kode di atas, seluruh kode di dalam kurung kurawal dikomentari sehingga tidak akan dikompilasi dan diabaikan oleh kompiler.

3. Komentar Dokumentasi

Digunakan untuk menghasilkan dokumentasi API resmi. Ketika orang lain menggunakan pustaka buatanmu, mereka bisa membaca petunjuk penggunaan kelas, fungsi, parameter dan lainnya layaknya buku panduan.

1. Dua format penulisan

• Komentar dokumentasi satu baris: beberapa baris berurutan dengan ///, fungsinya sama dengan komentar dokumentasi multibaris. Perhatikan ada tiga garis miring.
• Komentar dokumentasi multibaris: dimulai dengan /** dan diakhiri */. Perhatikan ada tanda bintang tambahan di awal.

2. Aturan sintaks inti

1. Teks biasa di dalam komentar dokumentasi akan diabaikan oleh penganalisis kode;
2. Sintaks khusus: identitas dibungkus kurung siku [] dapat merujuk kelas, metode, field, variabel tingkat atas, fungsi dan parameter;
3. Nama di dalam kurung siku akan diresolusi dalam lingkup leksikal kode yang dikomentari;
4. Setelah dokumentasi dihasilkan, [identitas] akan otomatis menjadi tautan hiper menuju dokumentasi terkait.

Contoh

// Komentar satu baris biasa: definisi kelas pakan
class Food {
  String type;
  // Komentar satu baris: jumlah ikat pakan
  int baleCount;

  Food(this.type, this.baleCount);
}

/*
Komentar multibaris biasa:
Enum jenis aktivitas untuk metode gerak llama
Demonstrasi komentar bersarang
/* Komentar bersarang bagian dalam */
*/
enum Activity {
  walk,
  run,
  graze
}

/// Hewan camelidae domestik Amerika Selatan (llama, nama ilmiah Lama glama)
///
/// Sebelum zaman Columbus, peradaban Andes memanfaatkan llama sebagai sumber daging dan hewan angkut.
///
/// Sama seperti hewan lain, llama memerlukan pakan: gunakan pakan tipe [Food] dan panggil metode [feed].
class Llama {
  String? name;

  /// Berikan pakan [food] yang ditentukan ke llama
  ///
  /// Satu llama biasanya menghabiskan satu ikat jerami setiap minggu.
  void feed(Food food) {
    // Komentar satu baris: cetak informasi pemberian makan
    print("${name} memakan ${food.baleCount} ikat ${food.type}");
  }

  /// Buat llama melakukan aktivitas [activity] selama [timeLimit] menit
  void exercise(Activity activity, int timeLimit) {
    print("${name} melakukan aktivitas ${activity.name} selama ${timeLimit} menit");
  }
}

void main() {
  // TODO: Nantinya bisa dikembangkan fitur kelola banyak llama
  Llama larry = Llama();
  larry.name = "Larry";

  // Buat pakan jerami
  Food hay = Food("jerami", 1);
  larry.feed(hay);

  // Llama jalan-jalan selama 20 menit
  larry.exercise(Activity.walk, 20);
}
Code language: PHP (php)

Setelah dokumentasi dihasilkan: [feed] akan terhubung ke dokumentasi metode feed kelas saat ini, [Food] terhubung ke dokumentasi kelas Food.

D:\dartdemo\firstdart>dart run
Building package executable...
Built firstdart:firstdart.
Larry memakan 1 ikat jerami
Larry melakukan aktivitas walk selama 20 menit

D:\dartdemo\firstdart>dart doc
Documenting firstdart...
Discovering libraries...
Linking elements...
Precaching local docs for 136851 elements...
Initialized dartdoc with 50 libraries
Generating docs for library firstdart.dart from package:firstdart/firstdart.dart...
Found 0 warnings and 0 errors.
Documented 1 public library in 10.3 seconds
Success! Docs generated into d:\dartdemo\firstdart\doc\apiCode language: JavaScript (javascript)

Kemudian akan muncul folder doc di direktori proyek, buka folder tersebut untuk melihat dokumentasi yang dibuat

Alat Pendukung

1. Alat generator dokumentasi: dart doc Fungsi: menganalisis kode sumber Dart dan menghasilkan dokumentasi API format HTML secara otomatis. Dokumentasi API resmi Dart juga dibuat menggunakan alat ini.
2. Referensi standar penulisan komentar: Panduan resmi «Effective Dart: Documentation», berisi struktur dan gaya penulisan komentar standar.

Ringkasan

Tabel perbandingan

Jenis Komentar	Simbol Awal	Multibaris	Bersarang	Kegunaan
Komentar satu baris	//	Tidak, hanya satu baris	Tidak bisa	Catatan sementara satu baris, daftar tugas TODO
Komentar multibaris biasa	/* */	Ya, banyak baris	Bisa bersarang	Nonaktifkan blok kode panjang, penjelasan panjang
Komentar dokumentasi	/// / /** */	Ya	Tidak disarankan	Tulis API kelas/method/variabel, hasilkan dokumentasi resmi, tautan identitas pakai []