PHPDocumentor เป็นเครื่องมือที่เขียนด้วย PHP สำหรับโปรแกรม PHP ที่มีคำอธิบายประกอบมาตรฐาน จะสามารถสร้างเอกสาร API พร้อมตัวอ้างอิงโยง การทำดัชนี และฟังก์ชันอื่นๆ ได้อย่างรวดเร็ว เวอร์ชันเก่าคือ phpdoc
1.phpDocumentor คืออะไร?
PHPDocumentor เป็นเครื่องมือที่เขียนด้วย PHP สำหรับโปรแกรม PHP ที่มีคำอธิบายประกอบมาตรฐาน จะสามารถสร้างเอกสาร API พร้อมตัวอ้างอิงโยง การทำดัชนี และฟังก์ชันอื่นๆ ได้อย่างรวดเร็ว เวอร์ชันเก่าคือ phpdoc เริ่มตั้งแต่ 1.3.0 โดยเปลี่ยนชื่อเป็น phpDocumentor เวอร์ชันใหม่เพิ่มการรองรับไวยากรณ์ php5 ในเวลาเดียวกัน สามารถสร้างเอกสารได้โดยการทำงานบนเบราว์เซอร์ไคลเอ็นต์ และสามารถแปลงเอกสารเป็นได้ PDF, HTML, CHM มีหลายรูปแบบซึ่งสะดวกมาก
เมื่อ PHPDocumentor ทำงาน มันจะสแกนซอร์สโค้ด PHP ภายใต้ไดเรกทอรีที่ระบุ สแกนคำหลัก สกัดกั้นความคิดเห็นที่จำเป็นต้องวิเคราะห์ จากนั้นวิเคราะห์แท็กพิเศษในความคิดเห็น สร้างไฟล์ xml จากนั้นขึ้นอยู่กับข้อมูลของ คลาสและโมดูลที่วิเคราะห์ สร้างดัชนีที่เกี่ยวข้อง สร้างไฟล์ xml และใช้เทมเพลตที่กำหนดเองเพื่อส่งออกไฟล์ในรูปแบบที่ระบุสำหรับไฟล์ xml ที่สร้างขึ้น
2. ติดตั้ง phpDocumentor
เช่นเดียวกับโมดูลอื่น ๆ ภายใต้ลูกแพร์ การติดตั้ง phpDocumentor ยังแบ่งออกเป็นสองวิธี: การติดตั้งอัตโนมัติและการติดตั้งด้วยตนเอง ทั้งสองวิธีสะดวกมาก:
ก. ติดตั้งผ่านลูกแพร์โดยอัตโนมัติและเข้าสู่บรรทัดคำสั่ง
ลูกแพร์ติดตั้ง PhpDocumentor
ข. ติดตั้ง PhpDocumentor เวอร์ชันล่าสุดด้วยตนเอง (ปัจจุบันคือ 1.4.0) ที่ http://manual.phpdoc.org/ และแตกไฟล์ออกมา
3. วิธีใช้ PhpDocumentor เพื่อสร้างบรรทัดคำสั่งเอกสารประกอบ:
ในไดเร็กทอรีที่มี phpDocumentor ให้ป้อน
Php-h
คุณจะได้รับรายการพารามิเตอร์โดยละเอียด ซึ่งมีพารามิเตอร์ที่สำคัญหลายประการดังนี้:
-f ชื่อของไฟล์ที่จะวิเคราะห์ หลายไฟล์คั่นด้วยเครื่องหมายจุลภาค
-d ไดเรกทอรีที่จะวิเคราะห์ หลายไดเรกทอรีคั่นด้วยเครื่องหมายจุลภาค
-t เส้นทางการจัดเก็บของเอกสารที่สร้างขึ้น
-o รูปแบบเอกสารเอาต์พุต โครงสร้างคือรูปแบบเอาต์พุต: ชื่อตัวแปลง: ไดเร็กทอรีเทมเพลต
ตัวอย่างเช่น: phpdoc -o HTML:frames:earthli -f test.php -t docs
เว็บอินเตอร์เฟสถูกสร้างขึ้นใน phpdoc ใหม่ นอกเหนือจากการสร้างเอกสารบนบรรทัดคำสั่งแล้ว คุณยังสามารถสร้างเอกสารบนเบราว์เซอร์ไคลเอนต์ได้ด้วย วิธีการเฉพาะคือการวางเนื้อหาของ PhpDocumentor ลงในไดเร็กทอรี apache เพื่อให้สามารถเป็นอันดับแรกได้ เข้าถึงได้ผ่านเบราว์เซอร์ อินเทอร์เฟซต่อไปนี้จะปรากฏขึ้นหลังจากเข้าถึง:
คลิกปุ่มไฟล์เพื่อเลือกไฟล์ php หรือโฟลเดอร์ที่จะประมวลผล คุณยังสามารถเพิกเฉยต่อการประมวลผลไฟล์บางไฟล์ได้โดยระบุไฟล์ที่จะละเว้นในอินเทอร์เฟซนี้
จากนั้นคลิกปุ่มเอาต์พุตเพื่อเลือกเส้นทางการจัดเก็บและรูปแบบของเอกสารที่สร้างขึ้น
สุดท้ายให้คลิกสร้าง จากนั้น phpdocumentor จะเริ่มสร้างเอกสารโดยอัตโนมัติ ความคืบหน้าและสถานะของการสร้างจะแสดงที่ด้านล่าง หากสำเร็จ ก็จะปรากฏขึ้น
เวลาเอกสารทั้งหมด: 1 วินาที
เสร็จแล้ว
ปฏิบัติการเสร็จสิ้น!!
จากนั้นเราจะสามารถดูเอกสารที่สร้างขึ้นได้ หากอยู่ในรูปแบบ pdf ชื่อจะมีค่าเริ่มต้นเป็น document.pdf
4. เพิ่มความคิดเห็นมาตรฐานให้กับโค้ด php
PHPDocument สร้างเอกสารจากความคิดเห็นในซอร์สโค้ดของคุณ ดังนั้นกระบวนการแสดงความคิดเห็นเกี่ยวกับโปรแกรมของคุณจึงเป็นกระบวนการรวบรวมเอกสารด้วย
จากมุมมองนี้ PHPdoc สนับสนุนให้คุณพัฒนานิสัยการเขียนโปรแกรมที่ดีและพยายามใช้ข้อกำหนดและข้อความที่ชัดเจนเพื่ออธิบายประกอบโปรแกรมของคุณ ในเวลาเดียวกันก็ช่วยหลีกเลี่ยงปัญหาการไม่ซิงโครไนซ์ระหว่างการเตรียมเอกสารและเอกสารไม่มากก็น้อย อัปเดตในภายหลัง
ใน phpdocumentor ความคิดเห็นจะถูกแบ่งออกเป็นความคิดเห็นเกี่ยวกับเอกสารและความคิดเห็นที่ไม่ใช่เอกสาร
ความคิดเห็นที่เรียกว่าเอกสารประกอบคือความคิดเห็นหลายบรรทัดที่อยู่หน้าคำหลักเฉพาะ หมายถึงคำหลักที่สามารถวิเคราะห์ได้โดย phpdoc เช่น class, var เป็นต้น สำหรับรายละเอียด โปรดดูภาคผนวก 1
ความคิดเห็นที่ไม่นำหน้าคีย์เวิร์ดหรือไม่ได้มาตรฐานเรียกว่าความคิดเห็นที่ไม่ใช่เอกสารประกอบ ความคิดเห็นเหล่านี้จะไม่ได้รับการวิเคราะห์โดย phpdoc และจะไม่ปรากฏในข้อความ API ที่คุณสร้าง
3.2 วิธีเขียนความคิดเห็นเกี่ยวกับเอกสาร:
ความคิดเห็นในเอกสารทั้งหมดเป็นความคิดเห็นหลายบรรทัดที่ขึ้นต้นด้วย /** ซึ่งเรียกว่า DocBlock ใน phpDocumentor หมายถึงข้อมูลช่วยเหลือเกี่ยวกับคำหลักบางคำที่เขียนโดยนักพัฒนาซอฟต์แวร์ เพื่อให้ผู้อื่นสามารถทราบสิ่งนี้ผ่านวัตถุประสงค์เฉพาะของคำหลักนั้น และวิธีการใช้งาน PhpDocumentor ระบุว่า DocBlock มีข้อมูลต่อไปนี้:
1. ฟังก์ชั่นคำอธิบายโดยย่อ
2. พื้นที่คำอธิบายโดยละเอียด
3. แท็ก
บรรทัดแรกของคำอธิบายเอกสารคือพื้นที่คำอธิบายฟังก์ชัน โดยทั่วไปข้อความจะอธิบายฟังก์ชันของคลาส วิธีการ หรือฟังก์ชันนี้โดยย่อ ข้อความของคำอธิบายฟังก์ชันจะแสดงในพื้นที่ดัชนีในเอกสารที่สร้างขึ้น เนื้อหาของพื้นที่คำอธิบายฟังก์ชันสามารถลงท้ายด้วยบรรทัดว่าง หรือ หลังจากพื้นที่คำอธิบายฟังก์ชันเป็นบรรทัดว่าง ตามด้วยพื้นที่คำอธิบายโดยละเอียด ส่วนนี้จะอธิบายฟังก์ชันและวัตถุประสงค์ของ API ของคุณเป็นหลัก หากเป็นไปได้ คุณยังสามารถ ตัวอย่างการใช้งาน ฯลฯ ในส่วนนี้ คุณควรเน้นที่การชี้แจงวัตถุประสงค์ทั่วไปและการใช้งานฟังก์ชันหรือวิธีการของ API และระบุว่าเป็นข้อมูลข้ามแพลตฟอร์มหรือไม่ (หากเกี่ยวข้อง) คุณควรปฏิบัติต่อข้อมูลดังกล่าวแตกต่างจากข้อมูลทั่วไป วิธีการปกติคือการขึ้นบรรทัดใหม่ จากนั้นเขียนข้อควรระวังหรือข้อมูลพิเศษบนแพลตฟอร์มเฉพาะ ข้อมูลนี้ควรจะเพียงพอเพื่อให้ผู้อ่านของคุณสามารถเขียนข้อมูลการทดสอบที่เกี่ยวข้อง เช่น เงื่อนไขขอบเขต ช่วงพารามิเตอร์ จุดพัก ฯลฯ
หลังจากนั้นก็จะมีบรรทัดว่าง ตามด้วยแท็กเอกสาร ซึ่งระบุข้อมูลทางเทคนิคบางอย่าง ส่วนใหญ่เป็นประเภทพารามิเตอร์การโทร ค่าและประเภทที่ส่งคืน ความสัมพันธ์ของการสืบทอด วิธีการ/ฟังก์ชันที่เกี่ยวข้อง เป็นต้น
เกี่ยวกับการมาร์กเอกสาร โปรดดูรายละเอียดที่ส่วนที่ 4: การมาร์กเอกสาร
แท็กเช่น <b> <code> สามารถใช้ในความคิดเห็นของเอกสารได้ โปรดดูรายละเอียดในภาคผนวก 2
ต่อไปนี้เป็นตัวอย่างความคิดเห็นเกี่ยวกับเอกสาร
/**
* ฟังก์ชั่นเพิ่ม ดำเนินการบวกตัวเลขสองตัว
-
* การคำนวณการบวกอย่างง่าย ฟังก์ชันยอมรับตัวเลข a และ b สองตัว แล้วส่งกลับผลรวม c
-
* @param int เพิ่ม
* @param int summand
* @return จำนวนเต็ม
-
ฟังก์ชั่น เพิ่ม($a, $b) {
ส่งคืน $a+$b;
}
เอกสารที่สร้างขึ้นมีดังนี้:
เพิ่ม
จำนวนเต็ม เพิ่ม(int $a, int $b)
[บรรทัดที่ 45]
ฟังก์ชั่น add ใช้การบวกตัวเลขสองตัว
ค่าคงที่คือการคำนวณการบวกอย่างง่าย ฟังก์ชันยอมรับตัวเลข a และ b สองตัว แล้วส่งคืนผลรวม c
พารามิเตอร์
• int $a - เพิ่ม
• int $b - บทสรุป
5. แท็กเอกสาร:
ขอบเขตการใช้แท็กเอกสารอ้างอิงถึงคำสำคัญหรือแท็กเอกสารอื่นๆ ที่แท็กสามารถใช้เพื่อแก้ไขได้
แท็กเอกสารทั้งหมดขึ้นต้นด้วย @ หลัง * ในแต่ละบรรทัด หากเครื่องหมาย @ ปรากฏขึ้นตรงกลางย่อหน้า เครื่องหมายนั้นจะถือเป็นเนื้อหาปกติและจะถูกละเว้น
@เข้าถึง
ขอบเขตการใช้งาน: คลาส, ฟังก์ชัน, var, กำหนด, โมดูล
แท็กนี้ใช้เพื่อระบุสิทธิ์การเข้าถึงของคำสำคัญ: ส่วนตัว สาธารณะ หรือที่ได้รับการป้องกัน
@ผู้เขียน
ระบุผู้เขียน
@ลิขสิทธิ์
ขอบเขตการใช้งาน: คลาส, ฟังก์ชัน, var, กำหนด, โมดูล, การใช้งาน
ระบุข้อมูลลิขสิทธิ์
@เลิกใช้แล้ว
ขอบเขตการใช้งาน: คลาส, ฟังก์ชัน, var, กำหนด, โมดูล, เนื้อหา, โกลบอล, รวม
ระบุคำหลักที่ไม่ได้ใช้หรือล้าสมัย
@ตัวอย่าง
แท็กนี้ใช้เพื่อแยกวิเคราะห์เนื้อหาไฟล์และไฮไลต์ Phpdoc จะพยายามอ่านเนื้อหาไฟล์จากเส้นทางไฟล์ที่กำหนดโดยแท็กนี้
@const
ขอบเขตการใช้งาน: กำหนด
ใช้เพื่อระบุค่าคงที่ที่กำหนดไว้ใน php
@สุดท้าย
ขอบเขตการใช้งาน: คลาส, ฟังก์ชัน, var
บ่งชี้ว่าคำหลักนั้นเป็นคลาส วิธีการ หรือคุณลักษณะขั้นสุดท้าย และห้ามมิให้รับหรือแก้ไข
@ไฟล์ซอร์ส
คล้ายกับตัวอย่าง ยกเว้นว่าแท็กนี้จะอ่านเนื้อหาของไฟล์ php ที่แยกวิเคราะห์ในปัจจุบันโดยตรงและแสดงมัน
@ทั่วโลก
ระบุตัวแปรร่วมที่อ้างอิงในฟังก์ชันนี้
@ingore
ใช้เพื่อละเว้นคำสำคัญที่ระบุในเอกสาร
@ใบอนุญาต
เทียบเท่ากับ <a> ในแท็ก html อันดับแรกคือ URL จากนั้นเนื้อหาที่จะแสดง เช่น <a href=”http://www.baidu.com”>Baidu</a>
คุณสามารถเขียน @license http://www.baidu.com Baidu
@ลิงค์
คล้ายกับใบอนุญาต
แต่คุณยังสามารถชี้ไปที่คำสำคัญใดๆ ในเอกสารผ่านลิงก์ได้
@ชื่อ
ระบุนามแฝงสำหรับคำหลัก
@บรรจุุภัณฑ์
ขอบเขตการใช้งาน: ระดับเพจ -> กำหนด, ฟังก์ชัน, รวม
ระดับคลาส -> คลาส, var, วิธีการ
ใช้เพื่อจัดกลุ่มคำหลักหนึ่งหรือหลายคำเป็นกลุ่มตามตรรกะ
@abstrcut
บ่งชี้ว่าคลาสปัจจุบันเป็นคลาสนามธรรม
@พาราม
ระบุพารามิเตอร์ของฟังก์ชัน
@กลับ
ระบุตัวชี้กลับของวิธีการหรือฟังก์ชัน
@คงที่
บ่งชี้ว่าคำสำคัญเป็นแบบคงที่
@var
ระบุประเภทตัวแปร
@รุ่น
ระบุข้อมูลเวอร์ชัน
@todo
ระบุประเด็นที่ควรปรับปรุงหรือไม่ดำเนินการ
@พ่น
บ่งชี้ถึงข้อยกเว้นข้อผิดพลาดที่ฟังก์ชันนี้อาจเกิดขึ้น ในกรณีที่รุนแรง ดังที่กล่าวไว้ข้างต้น แท็กเอกสารธรรมดาจะต้องถูกทำเครื่องหมายด้วย @ ที่จุดเริ่มต้นของแต่ละบรรทัด นอกจากนี้ยังมีแท็กที่เรียกว่าแท็กอินไลน์ โดยใช้วิธี {@ } โดยเฉพาะสิ่งต่อไปนี้:
{@ลิงก์ }
การใช้งานเหมือนกับ @link
{@แหล่งที่มา }
แสดงเนื้อหาของฟังก์ชันหรือวิธีการ
6. ข้อกำหนดคำอธิบายประกอบบางประการ
ก. ความคิดเห็นจะต้องเป็น
-
* XXXXXXX
-
รูปร่าง
ข. สำหรับฟังก์ชันที่อ้างอิงตัวแปรโกลบอล ต้องใช้แท็ก glboal
c. สำหรับตัวแปร ประเภทของตัวแปรจะต้องถูกทำเครื่องหมายด้วย var (int, string, bool...)
d ฟังก์ชันจะต้องระบุพารามิเตอร์และส่งคืนค่าผ่านพารามิเตอร์และแท็กส่งคืน
จ. สำหรับคำหลักที่ปรากฏสองครั้งขึ้นไป ให้ละเว้นคำหลักที่ซ้ำซ้อนผ่านทาง ingore และเก็บไว้เพียงคำเดียว
ฉ. ในกรณีที่มีการเรียกใช้ฟังก์ชันหรือคลาสอื่นๆ ควรใช้ลิงก์หรือแท็กอื่นๆ เพื่อเชื่อมโยงไปยังส่วนที่เกี่ยวข้องเพื่ออำนวยความสะดวกในการอ่านเอกสาร
g. ใช้ความคิดเห็นที่ไม่ใช่เอกสารในกรณีที่จำเป็นเพื่อปรับปรุงความสามารถในการอ่านโค้ด
ซ. อธิบายเนื้อหาให้กระชับและตรงประเด็น โดยใช้วลีแทนประโยคทุกครั้งที่เป็นไปได้
i. ตัวแปรโกลบอล ตัวแปรคงที่ และค่าคงที่ต้องได้รับการประกาศด้วยแท็กที่เกี่ยวข้อง
7. สรุป
phpDocumentor เป็นเครื่องมือสร้างเอกสารอัตโนมัติที่ทรงพลังมาก สามารถช่วยให้เราเขียนความคิดเห็นที่เป็นมาตรฐานและสร้างเอกสารที่มีโครงสร้างชัดเจนและเข้าใจง่าย ซึ่งมีประโยชน์มากสำหรับการอัปเกรดโค้ด การบำรุงรักษา การส่งมอบ ฯลฯ
สำหรับคำอธิบายโดยละเอียดเพิ่มเติมของ phpDocumentor คุณสามารถไปที่เว็บไซต์อย่างเป็นทางการ
http://manual.phpdoc.org/View
8. ภาคผนวก ภาคผนวก 1:
คำหลักที่ phpdoc ยอมรับ:
รวม
จำเป็นต้อง
รวม_ครั้งเดียว
need_once
กำหนด
การทำงาน
ทั่วโลก
ระดับ
ภาคผนวก 2
แท็กที่สามารถใช้ในเอกสาร
<ข>
<รหัส>
<br>
<เคดีบี>
<li>
<ก่อน>
<ul>
<ตัวอย่าง>
<var>
ภาคผนวก 3:
โค้ด php พร้อมความคิดเห็นตามรูปแบบบัญญัติ:
<?php
-
* ไฟล์ตัวอย่าง 2, phpDocumentor Quickstart
-
* ไฟล์นี้แสดงข้อมูลมากมายที่สามารถรวมไว้ได้
* เอกสารในโค้ดผ่าน DocBlocks และแท็ก
* @ผู้เขียน เกร็ก บีเวอร์ < [email protected] >
* @เวอร์ชั่น 1.0
* @ตัวอย่างแพ็คเกจ
-
// ไฟล์ตัวอย่าง #1
-
* รวมค่าจำลองเพื่อสาธิตพลังการแยกวิเคราะห์ของ phpDocumentor
-
include_once 'sample3.php';
-
* การประกาศตัวแปรส่วนกลางพิเศษ DocBlock
* @global จำนวนเต็ม $GLOBALS['_myvar']
* @ชื่อ $_myvar
-
$GLOBALS['_myvar'] = 6;
-
*ค่าคงที่
-
-
* ค่าคงที่แรก
-
กำหนด('การทดสอบ', 6);
-
* ค่าคงที่ที่สอง
-
กำหนด('ค่าคงที่อื่น', strlen('สวัสดี'));
-
* ตัวอย่างฟังก์ชัน docblock
* @global string บันทึกข้อเท็จจริงที่ว่าฟังก์ชันนี้ใช้ $_myvar
* @staticvar integer $staticvar นี่คือสิ่งที่ส่งคืนจริงๆ
* @param string $param1 ชื่อที่จะประกาศ
* @param string ค่า $param2 ของชื่อ
* @return จำนวนเต็ม
-
ฟังก์ชั่น firstFunc($param1, $param2 = 'เป็นทางเลือก') {
คงที่ $staticvar = 7;
ทั่วโลก $_myvar;
ส่งคืน $staticvar;
-
-
* คลาสตัวอย่างแรกนี้อยู่ในแพ็คเกจเดียวกันกับ
*เนื้อหาขั้นตอนในตอนต้นของไฟล์
* @ตัวอย่างแพ็คเกจ
* คลาส @subpackage
-
คลาส myclass {
-
* ตัวอย่างตัวแปรส่วนตัว ซึ่งสามารถซ่อนได้ด้วย --parseprivate
*ตัวเลือก
* @accessprivate
* @var จำนวนเต็ม|string
-
var $firstvar = 6;
-
* @link http://www.example.com ลิงค์ตัวอย่าง
* @ดูคลาสของฉัน()
* @ใช้การทดสอบ ค่าคงที่อื่น
* @var อาร์เรย์
-
var $วินาทีวาร์ =
อาร์เรย์(
'สิ่งของ' =>
อาร์เรย์(
6,
17,
'ตัวนิ่ม'
-
การทดสอบ => ค่าคงที่อื่น
-
-
* Constructor ตั้งค่า {@link $firstvar}
-
ฟังก์ชั่น myclass() {
$นี่->firstvar = 7;
-
-
* ส่งคืนสิ่งของตาม $paramie
* @param บูลีน $paramie
* @return จำนวนเต็ม|babyclass
-
ฟังก์ชั่น parentfunc($paramie) {
ถ้า ($พารามี) {
กลับ 6;
} อื่น {
คืนคลาสเด็กใหม่
-
-
-
-
* @แพ็คเกจ ตัวอย่าง1
-
คลาส babyclass ขยาย myclass {
-
* คำตอบของชีวิต จักรวาล และทุกสิ่ง
* @var จำนวนเต็ม
-
var $วินาทีวาร์ = 42;
-
* ค่าการกำหนดค่า
* @var อาร์เรย์
-
var $thirdvar;
-
* เรียกตัวสร้างพาเรนต์ จากนั้นเพิ่มค่า {@link $firstvar}
-
ฟังก์ชั่น babyclass() {
ผู้ปกครอง::myclass();
$นี่->firstvar++;
-
-
* สิ่งนี้จะส่งคืน myclass เสมอ
* @param ละเว้น $paramie
* @return myclass
-
ฟังก์ชั่น parentfunc($paramie) {
ส่งคืน myclass ใหม่
-
-
-