PODS modul
Dokumentasi untuk modul Perl ditulis dalam bahasa markup sederhana yang disebut POD (Plain Old Dokumentasi).
Halaman ini menunjukkan bagaimana menulis POD untuk modul Perl. Jika Anda mematuhi gaya ini, maka akan lebih mudah bagi orang lain untuk membaca dan memahami dokumentasi Anda.
h2xs
menempatkan POD kerangka di akhir .pm
berkas yang menulis. Baca PODS dalam modul yang ada untuk contoh tambahan.
= NAME head1 Geometri :: Lingkaran - mengelola lingkaran |
The NAME Bagian memberi nama modul dan deskripsi satu baris.
Nama dan deskripsi dipisahkan dengan tanda hubung. Hal ini penting untuk mematuhi format ini sehingga POD dapat dikonversi ke halaman man yang tepat. |
= head1 SINOPSIS penggunaan Geometri :: Lingkaran $ lingkaran = baru Geometri :: Lingkaran $ x, $ y, $ r ($ x, $ y) = $ circle-> pusat; $ radius = $ circle-> radius; $ daerah = $ circle-> daerah $ pi = $ Geometri :: Lingkaran :: PI; |
The SYNOPSIS bagian menunjukkan langkah-langkah penting dalam menggunakan modul: pernyataan penggunaan, subrutin apapun, metode kelas atau variabel, dan semua metode objek. Metode panggilan harus menunjukkan parameter dan nilai kembali.
Indent setiap baris dalam sinopsis. Hal ini membuat sebuah paragraf verbatim, dan memastikan bahwa keselarasan Anda akan dipertahankan. |
= head1 MEMBUTUHKAN Perl5.8.8, Eksportir, Geometri :: Titik |
The REQUIRES Bagian memberitahu pengguna apa yang akan mereka butuhkan untuk menggunakan modul. |
= head1 EKSPOR Tidak |
The EXPORTS Bagian memberitahu pengguna apa modul akan lakukan untuk namespace mereka jika mereka use itu. |
= head1 Uraian Geometri :: Lingkaran mengelola lingkaran. Metode yang disediakan untuk menciptakan lingkaran dan komputasi daerah mereka. |
Ini adalah deskripsi dari modul.
Ini harus ditulis dalam istilah yang relevan dengan pengguna, bukan programmer.
|
= METODE head1 = head2 Creation = lebih dari 4 = Item Geometri baru :: Lingkaran $ x, $ y, $ radius Membuat dan mengembalikan objek Geometry :: Lingkaran baru dengan pusat ($ x, $ y) dan jari-jari $ radius. = kembali = Akses head2 = lebih dari 4 = Item $ circle-> pusat mengembalikan daftar x, y koordinat pusat lingkaran. dalam konteks skalar, mengembalikan referensi array. = Item $ circle-> radius mengembalikan radius lingkaran. = Item $ circle-> daerah Mengembalikan daerah lingkaran. = kembali |
The METHODS daftar bagian dan menjelaskan setiap metode di kelas.
Anda lebih lanjut dapat mengatur metode di bawah tingkat-2 judul, seperti |
= head1 CLASS VARIABEL = lebih dari 4 = Item $ Geometri :: Lingkaran :: PI Rasio lingkar lingkaran dengan diameternya. = kembali |
The CLASS VARIABLES bagian berisi variabel paket dalam API. |
= DIAGNOSTIK head1 = lebih dari 4 = Item radius Negatif (F) Lingkaran mungkin tidak dibuat dengan radius negatif. = kembali |
The DIAGNOSTICS Bagian memberikan teks setiap pesan kesalahan modul dapat menghasilkan, dan menjelaskan maknanya.
Pesan kesalahan diklasifikasikan sebagai berikut: (W) Sebuah peringatan (opsional) (D) Sebuah bantahan (opsional) (S) Sebuah peringatan keras (wajib) (F) Sebuah kesalahan fatal (trappable) (X) Sebuah kesalahan yang sangat fatal yang (non-trappable) |
= head1 PENULIS AU Thor, [email protected] |
Anda harus menyertakan nama dan alamat email, dalam kasus ada kebutuhan untuk menghubungi Anda mengenai modul. |
= head1 LIHAT JUGA perl (1), Geometry :: Lapangan |
Ini adalah daftar biasa program terkait dan modul. |
= memotong |
The =cut garis menandai akhir dari POD teks.
Beberapa orang mendistribusikan bagian POD seluruh kode sumber mereka. Perl mengakui bagian POD dan mengabaikan mereka. |