Pengenalan kepada PHPDOC

mata teras

phpDoc (phpdocumentor) adalah alat yang berkuasa yang membantu pemaju menulis dokumen kod melalui anotasi format khas. Ia boleh menghasilkan dokumen dalam pelbagai format, seperti HTML, PDF, dan CHM, yang boleh diekstrak melalui antara muka web atau antara muka baris arahan.
phpDoc menggunakan docBlocks (ulasan gaya C-line) untuk mendokumenkan blok kod. DocBlocks mengandungi tiga bahagian pilihan: penerangan ringkas, penerangan terperinci, dan tag. Tag bermula dengan simbol
• , yang menentukan maklumat tambahan mengenai kod tersebut. @
Pakej PHPDOC digunakan untuk mengumpulkan elemen kod yang relevan dalam dokumen yang dihasilkan. Anda boleh menentukan pakej untuk fail dan kelas menggunakan tag
• dan @package dalam tahap fail atau kelas peringkat kelas. @subpackage
PHPDOC boleh menulis dokumen untuk pelbagai elemen kod, termasuk fail, kelas, fungsi dan kaedah, sifat kelas, pembolehubah global,
• dan include()/require(). Unsur -unsur ini boleh menggunakan tag umum tertentu, tetapi masing -masing mempunyai tag tertentu. define()
Alat baris arahan PHPDOC digunakan untuk menjana dokumen mesra pengguna berdasarkan kod PHP yang telah ditulis. Alat ini menawarkan pelbagai format dokumen. Bagi pengguna yang tidak biasa dengan antara muka baris arahan, PHPDOC juga menyediakan antara muka web.

Kod membaca yang ditulis oleh orang lain (yang belum mengalaminya?) Adalah tugas yang sukar. "Kod gaya pasta" yang berantakan bercampur dengan sejumlah besar pembolehubah yang bernama pelik, menjadikannya pening. Adakah fungsi ini mengharapkan rentetan atau tatasusunan? Adakah bilangan bulat atau objek yang berubah -ubah ini? Selepas berjam -jam penjejakan kod dan cuba memahami fungsi setiap bahagian, adalah perkara biasa untuk menyerah dan menulis semula keseluruhan kod dari awal - ia adalah pembaziran masa berharga anda. PHPDOC (nama pendek untuk phpDocumentor) adalah alat yang berkuasa yang membolehkan anda dengan mudah menulis dokumen kod dengan komen dalam format khas. Dokumen bukan sahaja tersedia dalam kod sumber, tetapi juga dokumen profesional yang diekstrak melalui antara muka web atau antara muka baris arahan. Hasilnya boleh dalam pelbagai format seperti HTML, PDF, dan CHM. Di samping itu, banyak IDE yang menyediakan penyempurnaan kod boleh menghuraikan komen phpDoc dan memberikan ciri -ciri praktikal seperti jenis petikan. Dengan menggunakan PHPDOC, anda boleh memudahkan orang lain (dan diri anda) untuk memahami kod anda -walaupun selepas minggu, bulan, atau bahkan bertahun -tahun selepas menulisnya. Cara paling mudah untuk memasang phpDoc adalah menggunakan pir. Sudah tentu, pir mesti dipasang sebelum anda berbuat demikian. Jika anda tidak memasang pir, ikuti arahan di pear.php.net/manual/en/installation.php. Dalam artikel ini, saya akan menunjukkan kepada anda bagaimana untuk menghasilkan dokumen yang indah dan mesra pengguna dari awal hingga akhir dengan PHPDOC.

docblocks

DocBlock adalah komen gaya C-gaya yang digunakan untuk menulis dokumen untuk blok kod. Ia bermula dengan

dan setiap baris mempunyai asterisk. Berikut adalah contoh: /**

<?php
/**
 * 计算数组中每个元素的平方和
 *
 * 循环遍历数组中的每个元素，将其平方，并将其添加到总和中。返回总和。
 *
 * 此函数也可以使用 array_reduce() 实现；
 *
 * @param array $arr
 * @return int
 * @throws Exception 如果数组中的元素不是整数
 */
function sumOfSquares($arr) {
    $total = 0;
    foreach ($arr as $val) {
        if (!is_int($val)) {
            throw new Exception("Element is not an integer!");
        }
        $total += $val * $val;
    }
    return $total;
}

DocBlocks mengandungi tiga bahagian: penerangan ringkas, penerangan terperinci, dan label. Ketiga -tiga bahagian adalah pilihan. Penerangan ringkas adalah penerangan ringkas yang berakhir dengan garis baru atau tempoh. Rutin analitik phpDoc adalah pintar; Keterangan terperinci adalah kandungan utama dokumen; Kedua -dua deskripsi terperinci dan deskripsi pendek boleh mengandungi elemen HTML tertentu untuk pemformatan. Tag HTML yang tidak disokong akan dipaparkan sebagai teks biasa. PHPDOC boleh menjana dokumen dalam pelbagai format, jadi tag HTML tidak semestinya diberikan seperti yang mereka lakukan dalam fail HTML; Jika anda perlu memaparkan tag HTML sebagai teks, gunakan kurungan berganda. Contohnya:

Seksyen tag

<?php
/**
 * 这里是斜体标签的示例： >Hello, world!>
 */

DocBlock mengandungi bilangan tag khas yang diwakili oleh simbol

. Tag digunakan untuk menentukan maklumat tambahan, seperti parameter yang dijangkakan dan jenis mereka. Kebanyakan tag mesti berada di baris mereka sendiri, tetapi beberapa tag boleh digariskan. Tag sebaris disertakan dalam pendakap keriting dan boleh muncul dalam penerangan terperinci dan penerangan ringkas. Untuk senarai lengkap tag, lihat dokumentasi PHPDOC yang berkaitan. Jika anda memerlukan garis untuk bermula dengan simbol @ tetapi tidak mahu mentafsirkannya sebagai label, anda boleh melepaskannya dengan backslash. PHPDOC secara automatik akan mengenal pasti dan menghuraikan senarai teks dalam penerangan terperinci dan penerangan ringkas. Walau bagaimanapun, ia tidak menghuraikan senarai bersarang dengan betul. Jika anda mahu menggunakan senarai bersarang, gunakan tag HTML. Berikut adalah contoh untuk menggambarkan apa yang saya maksudkan: @

<?php
/**
 * 使用列表的示例
 *
 * PhpDoc 将正确解析此列表：
 * - 项目 #1
 * - 项目 #2
 * - 项目 #3
 *
 * 但不是这个列表：
 * - 项目 1
 *   - 项目 1.1
 *   - 项目 1.2
 * - 项目 2
 *
 * 请改用此方法创建嵌套列表：
 * 

*

项目 1

*

*

项目 1.1

*

项目 1.2

* *

项目 2

* */

(Kandungan berikut akan diringkaskan secara ringkas kerana batasan ruang dan maklumat utama yang ditahan)

Bag

Pakej PHPDOC digunakan untuk mengumpulkan elemen kod yang relevan dalam dokumen yang dihasilkan. Anda boleh menentukan pakej untuk fail dan kelas yang mengandungi kod yang ditulis untuk mewarisi pakej tersebut. Untuk menentukan pakej, tetapkan tag

di peringkat peringkat fail atau kelas kelas. (Tahap fail dan docblock peringkat kelas akan dibincangkan lebih lanjut di bahagian seterusnya). Nama pakej boleh mengandungi huruf, nombor, dash, garis bawah, dan kurungan persegi ("[" dan "]"). Berikut adalah contoh bagaimana untuk menentukan pakej fail: @package

<?php
/**
 * 这是一个文件级 DocBlock
 *
 * @package Some_Package
 */

Jika anda mempunyai pelbagai tahap pakej dan subpackages, anda boleh menggunakan tag

untuk menentukan subpackages. Berikut adalah contoh: @subpackage

<?php
/**
 * 这是一个类级 DocBlock
 *
 * @package    Some_Package
 * @subpackage Other
 */
class SomeClass {
}

Jika fail atau kelas tidak menentukan pakej, ia akan ditetapkan ke pakej lalai "lalai". Anda boleh menentukan pakej lain untuk digunakan secara lalai melalui pilihan baris arahan

. -dn

Dokumen apa yang boleh ditulis?

tidak semua elemen kod boleh ditulis menggunakan docBlocks. Berikut adalah senarai elemen kod yang boleh ditulis dalam dokumen:

• Fail
• kategori
• Fungsi dan Kaedah
• atribut kelas
• pembolehubah global
• include()/require()
• define()
Semua elemen ini boleh menggunakan label biasa tertentu, tetapi setiap elemen mempunyai label khusus untuk elemen tersebut. Saya akan merangkumi beberapa elemen dan tag yang biasanya digunakan untuk menulis dokumentasi untuk mereka.

(Contoh dokumentasi fail, kelas, fungsi dan kaedah akan ringkas, hanya deskripsi tag utama yang akan dikekalkan)

Menjana dokumen

Selepas menulis dokumentasi untuk kod PHP anda, anda perlu menghasilkan dokumen mesra pengguna daripadanya. Untuk melakukan ini, jalankan alat baris arahan phpDoc.

<?php
/**
 * 计算数组中每个元素的平方和
 *
 * 循环遍历数组中的每个元素，将其平方，并将其添加到总和中。返回总和。
 *
 * 此函数也可以使用 array_reduce() 实现；
 *
 * @param array $arr
 * @return int
 * @throws Exception 如果数组中的元素不是整数
 */
function sumOfSquares($arr) {
    $total = 0;
    foreach ($arr as $val) {
        if (!is_int($val)) {
            throw new Exception("Element is not an integer!");
        }
        $total += $val * $val;
    }
    return $total;
}

(penerangan parameter baris arahan akan singkat)

Bagi pengguna yang tidak biasa dengan antara muka baris arahan, PHPDOC juga menyediakan antara muka web. Dokumen ini tidak membincangkannya secara terperinci, tetapi anda boleh mengetahui lebih lanjut mengenai laman web rasmi PHPDOC, phpdoc.org.

Ringkasan

Dalam artikel ini, saya memperkenalkan anda kepada PHPDOC dan banyak ciri yang kuat. Saya telah menerangkan tujuan DocBlocks dan komponennya; Saya sangat mengesyorkan bahawa anda mula menggunakan PHPDOC dalam projek anda sendiri, walaupun ia hanya menulis dokumentasi untuk bahagian yang paling penting. Ia sangat mudah dan dapat menyelamatkan anda dan rakan -rakan anda banyak jam ketegangan dan kesakitan.

(bahagian FAQ akan ringkas, mengekalkan soalan teras dan jawapan pendek)

Atas ialah kandungan terperinci Pengenalan kepada PHPDOC. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!