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.

h2xsmenempatkan POD kerangka di akhir .pm berkas yang menulis. Baca PODS dalam modul yang ada untuk contoh tambahan.

 

= NAME head1 

Geometri :: Lingkaran - mengelola lingkaran
The NAMEBagian 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 useitu. 
= 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.

  • Apa fungsinya bagi pengguna?
  • Bagaimana kamu menggunakannya?
  • benda apa itu mendukung?
  • metode apa yang tidak memberikan?
 
= 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 METHODSdaftar bagian dan menjelaskan setiap metode di kelas.

Anda lebih lanjut dapat mengatur metode di bawah tingkat-2 judul, seperti Creation, Accessdan Utility.

 
= head1 CLASS VARIABEL 

= lebih dari 4 

= Item $ Geometri :: Lingkaran :: PI 

Rasio lingkar 
lingkaran dengan diameternya. 

= kembali
The CLASS VARIABLESbagian berisi variabel paket dalam API. 
= DIAGNOSTIK head1 

= lebih dari 4 

= Item radius Negatif 

(F) Lingkaran mungkin tidak dibuat dengan radius negatif. 

= kembali
The DIAGNOSTICSBagian 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 =cutgaris menandai akhir dari POD teks.

Beberapa orang mendistribusikan bagian POD seluruh kode sumber mereka. Perl mengakui bagian POD dan mengabaikan mereka.