Kode yang ditulis hari ini mudah dijalankan, tetapi enam bulan kemudian pertanyaannya berubah: fungsi ini menerima apa, mengembalikan apa, dan bagaimana memakainya? Dokumentasi yang baik hidup menempel pada kode itu sendiri — sebagai komentar help yang ditampilkan perintah help — sehingga tidak pernah terpisah dari implementasinya. Chapter ini membahas:

• Struktur help text fungsi yang profesional: H1 line, sintaks, input/output, contoh, See also.
• Help untuk skrip, hubungan dengan lookfor, dan doc.
• publish untuk mengubah skrip menjadi laporan HTML (MATLAB-only).

Help Text Fungsi #

Aturannya: blok komentar % yang diletakkan tepat setelah baris function menjadi help text. MATLAB membaca komentar beruntun tersebut, memotongnya di baris kosong pertama tanpa %, lalu menampilkan isinya saat kita memanggil help('namaFungsi'). Berkas hitungRata.m berikut memakai struktur lengkap:

function r = hitungRata(v)
%hitungRata Hitung rata-rata vektor.
%   r = hitungRata(v) mengembalikan rata-rata elemen vektor v.
%
%   Input:
%       v - vektor numerik
%
%   Output:
%       r - rata-rata (skalar)
%
%   Contoh:
%       r = hitungRata([10 20 30])   % menghasilkan 20
%
%   See also mean, sum.

r = sum(v) / numel(v);
end

Mari kita bedah baris-baris kode di atas:

1. Baris 2 (%hitungRata Hitung rata-rata vektor.): baris pertama disebut H1 line — nama program plus ringkasan satu baris. lookfor dan panel Files memakai H1 line ini sebagai “iklan” fungsi, jadi tulis H1 seperti judul yang dicari orang.
2. Baris 3 (% r = hitungRata(v) ...): sintaks pemanggilan beserta penjelasan keluarannya — kontrak fungsi dalam satu kalimat.
3. Baris 5-11 (Input:, Output:, Contoh:): daftar argumen dengan indentasi konsisten, lalu contoh pemakaian yang bisa disalin. Contoh yang benar-benar berjalan adalah dokumentasi yang tidak pernah basi.
4. Baris 13 (% See also mean, sum.): rujukan fungsi bertetangga. Di MATLAB, nama yang ditemukan di path otomatis menjadi hyperlink ke help-nya.
5. Baris 14 (baris kosong tanpa %): penutup blok help — komentar sesudahnya tidak lagi dianggap dokumentasi.

Setelah folder fungsi berada di path, help('hitungRata') menampilkan:

Output yang Dihasilkan:

hitungRata Hitung rata-rata vektor.
   r = hitungRata(v) mengembalikan rata-rata elemen vektor v.

   Input:
       v - vektor numerik

   Output:
       r - rata-rata (skalar)

   Contoh:
       r = hitungRata([10 20 30])   % menghasilkan 20

   See also mean, sum.

Struktur Help Profesional #

Tidak semua fungsi butuh semua bagian — fungsi dua baris cukup H1 line dan satu baris sintaks. Panduan proporsinya:

Perintah lookfor('kata kunci') memindai H1 line seluruh fungsi di path — contoh.m membuktikannya: lookfor('rata-rata') menemukan hitungRata tanpa perlu tahu nama fungsinya. Untuk kelas OOP, help NamaKelas menampilkan help dari komentar di awal blok classdef; pola penulisannya sama.

Help untuk Skrip #

Skrip tidak punya baris function, jadi help text-nya adalah blok komentar beruntun pertama di bagian paling atas berkas. Prefiks %% sekaligus menandai judul section di Live Editor:

%% Laporan Penjualan Bulanan
% Baca data penjualan lalu cetak ringkasan.
%   Jalankan langsung; hasil ditampilkan di Command Window.

help('laporanPenjualan') menampilkan blok tersebut. Sama seperti fungsi, blok komentar setelah baris kosong pertama sudah dianggap kode/komentar biasa, bukan dokumentasi.

publish: dari Kode ke Laporan #

publish menjalankan skrip kita sambil merekam kode, keluaran, dan figur yang dihasilkan, lalu menyusunnya menjadi dokumen HTML — dokumentasi sekaligus laporan. Sintaks intinya (MATLAB-only, tidak diuji runner karena perlu MATLAB desktop):

% MATLAB: hasilkan laporan dari skrip (MATLAB-ONLY)
publish('laporan.m')               % HTML -> subfolder html/
publish('laporan.m', 'pdf')        % format lain: pdf, doc, latex
opsi = struct('format', 'pdf', 'outputDir', 'docs');
publish('laporan.m', opsi)         % kontrol via struct opsi
berkas = publish('laporan.m');     % kembalikan path lengkap hasil

Secara default, berkas hasil dan gambar-gambarnya disimpan di subfolder html yang dibuat di sebelah berkas sumber. Section %% menjadi judul bagian, teks komentar menjadi paragraf naratif, dan keluaran Command Window direkam di bawah kodenya. Perintah doc hitungRata membuka versi help yang lebih lengkap di jendela Documentation browser — help untuk Command Window, doc untuk membaca sambil menjelajah.

README vs Help #

Keduanya saling melengkapi: README menjelaskan setup proyek (dibahas di chapter Struktur Proyek), help text menjelaskan tiap unit kode. contoh.m di bawah halaman ini menulis fungsi ber-help lengkap, memanggil help, menguji lookfor, menjalankan fungsi, lalu membersihkan berkasnya.

Output yang Dihasilkan (dari contoh.m lengkap):

hitungRata.m (17 baris) ditulis
== Bagian 2: help('hitungRata') ==
== Bagian 3: lookfor dan eksekusi ==
lookfor('rata-rata') menemukan hitungRata: 1
hitungRata([10 20 30]) = 20
== Bagian 4: pembersihan ==
fungsi demo dihapus: exist = 0

Baris di antara dua penanda bagian pada keluaran runner adalah tampilan help('hitungRata'): isi intinya sama dengan blok Output yang Dihasilkan sebelumnya, dengan tambahan header lokasi berkas dan catatan manual khas Octave.

Ringkasan #

Dokumentasi MATLAB hidup di komentar: blok % tepat setelah function (atau di awal skrip) menjadi help text yang ditampilkan help, dipindai lookfor lewat H1 line-nya, dan dibedah doc di browser. Struktur profesionalnya: H1, sintaks, input/output, contoh, See also, ditutup baris kosong. publish mengubah skrip menjadi laporan HTML dengan menjalankan kodenya — kuat, tetapi perlu hati-hati terhadap efek samping. Tulis semuanya untuk pembaca enam bulan di masa depan: diri kita sendiri yang sudah lupa konteks.