1. ภาพรวม
เอกสาร API ที่ดีเป็นหนึ่งในหลาย ๆ ปัจจัยที่ทำให้โครงการซอฟต์แวร์ประสบความสำเร็จโดยรวม
โชคดีที่ JDK เวอร์ชันที่ทันสมัยทั้งหมดมีเครื่องมือ Javadoc - สำหรับสร้างเอกสาร API จากความคิดเห็นที่มีอยู่ในซอร์สโค้ด
ข้อกำหนดเบื้องต้น:
- JDK 1.4 (แนะนำให้ใช้ JDK 7+ สำหรับปลั๊กอิน Maven Javadoc เวอร์ชันล่าสุด)
- เพิ่มโฟลเดอร์JDK / binให้กับตัวแปรสภาวะแวดล้อมPATH
- (ไม่บังคับ) IDE ที่มีเครื่องมือในตัว
2. ความคิดเห็น Javadoc
เริ่มกันที่ความคิดเห็น
โครงสร้างความคิดเห็น Javadoc มีลักษณะคล้ายกับความคิดเห็นหลายบรรทัดทั่วไป แต่ข้อแตกต่างที่สำคัญคือเครื่องหมายดอกจันพิเศษที่จุดเริ่มต้น:
// This is a single line comment /* * This is a regular multi-line comment */ /** * This is a Javadoc */ความคิดเห็นสไตล์ Javadoc อาจมีแท็ก HTML ด้วย
2.1. รูปแบบ Javadoc
ความคิดเห็น Javadoc อาจอยู่เหนือคลาสวิธีการหรือฟิลด์ใด ๆ ที่เราต้องการจัดทำเอกสาร
ความคิดเห็นเหล่านี้มักประกอบด้วยสองส่วน:
- คำอธิบายสิ่งที่เรากำลังแสดงความคิดเห็น
- แท็กบล็อกแบบสแตนด์อโลน (ทำเครื่องหมายด้วยสัญลักษณ์“ @ ”) ซึ่งอธิบายข้อมูลเมตาที่เฉพาะเจาะจง
เราจะใช้แท็กบล็อกทั่วไปในตัวอย่างของเรา สำหรับรายการแท็กบล็อกทั้งหมดโปรดไปที่คู่มืออ้างอิง
2.2. Javadoc ในระดับคลาส
มาดูกันว่าความคิดเห็น Javadoc ระดับคลาสจะเป็นอย่างไร:
/** * Hero is the main entity we'll be using to . . . * * Please see the {@link com.baeldung.javadoc.Person} class for true identity * @author Captain America * */ public class SuperHero extends Person { // fields and methods }เรามีคำอธิบายสั้น ๆ และแท็กบล็อกที่แตกต่างกันสองแบบ - แบบสแตนด์อโลนและแบบอินไลน์:
- แท็กแบบสแตนด์อโลนจะปรากฏหลังคำอธิบายโดยมีแท็กเป็นคำแรกในบรรทัดเช่นแท็ก@author
- แท็กแบบอินไลน์อาจปรากฏที่ใดก็ได้และล้อมรอบด้วยวงเล็บปีกกาเช่นแท็ก@linkในคำอธิบาย
ในตัวอย่างของเราเราสามารถเห็นแท็กบล็อกสองประเภทที่ใช้:
- {@link}ให้ลิงก์แบบอินไลน์ไปยังส่วนที่อ้างอิงของซอร์สโค้ดของเรา
- @ชื่อผู้แต่งที่เพิ่มคลาสเมธอดหรือฟิลด์ที่แสดงความคิดเห็น
2.3. Javadoc ที่ระดับฟิลด์
นอกจากนี้เรายังสามารถใช้คำอธิบายโดยไม่มีแท็กบล็อกเช่นนี้ในคลาสSuperHeroของเรา:
/** * The public name of a hero that is common knowledge */ private String heroName;ช่องส่วนตัวจะไม่สร้าง Javadoc ให้เว้นแต่เราจะส่งอ็อพชัน-privateไปยังคำสั่ง Javadoc อย่างชัดเจน
2.4. Javadoc ที่ระดับวิธีการ
วิธีการสามารถมีแท็กบล็อก Javadoc ได้หลายแบบ
ลองมาดูวิธีการที่เราใช้:
/** * This is a simple description of the method. . . * Superman! *
* @param incomingDamage the amount of incoming damage * @return the amount of health hero has after attack * @see HERO-402 * @since 1.0 */ public int successfullyAttacked(int incomingDamage) { // do things return 0; }successfullyAttackedวิธีมีทั้งรายละเอียดต่าง ๆ นานาและแท็กแบบสแตนด์อโลนบล็อก
มีแท็กบล็อกจำนวนมากเพื่อช่วยในการสร้างเอกสารที่เหมาะสมและเราสามารถรวมข้อมูลประเภทต่างๆได้ทุกประเภท เรายังสามารถใช้แท็ก HTML พื้นฐานในความคิดเห็น
มาดูแท็กที่เราพบในตัวอย่างด้านบน:
- @paramให้คำอธิบายที่เป็นประโยชน์เกี่ยวกับพารามิเตอร์หรืออินพุตของวิธีการที่ควรคาดหวัง
- @returnให้คำอธิบายว่าวิธีการใดจะได้หรือกลับมาได้
- @seeจะสร้างลิงก์ที่คล้ายกับแท็ก{@link}แต่จะมีมากกว่าในบริบทของข้อมูลอ้างอิงไม่ใช่แบบอินไลน์
- @sinceระบุเวอร์ชันที่เพิ่มคลาสฟิลด์หรือเมธอดในโปรเจ็กต์
- @versionระบุเวอร์ชันของซอฟต์แวร์ซึ่งมักใช้กับมาโคร% I% และ% G%
- @throwsใช้เพื่ออธิบายเพิ่มเติมในกรณีที่ซอฟต์แวร์คาดว่าจะมีข้อยกเว้น
- @deprecatedให้คำอธิบายว่าเหตุใดโค้ดจึงเลิกใช้งานเมื่ออาจเลิกใช้งานและทางเลือกอื่นคืออะไร
แม้ว่าทั้งสองส่วนจะเป็นทางเลือกในทางเทคนิค แต่เราต้องมีอย่างน้อยหนึ่งส่วนสำหรับเครื่องมือ Javadoc เพื่อสร้างสิ่งที่มีความหมาย
3. การสร้าง Javadoc
ในการสร้างหน้า Javadoc ของเราเราจะดูเครื่องมือบรรทัดคำสั่งที่มาพร้อมกับ JDK และปลั๊กอิน Maven
3.1. Javadoc Command Line Tool
เครื่องมือบรรทัดคำสั่ง Javadoc มีประสิทธิภาพมาก แต่มีความซับซ้อนบางอย่างแนบมาด้วย
การรันคำสั่งjavadocโดยไม่มีตัวเลือกหรือพารามิเตอร์ใด ๆ จะทำให้เกิดข้อผิดพลาดและพารามิเตอร์เอาต์พุตตามที่คาดไว้
อย่างน้อยเราจะต้องระบุแพ็คเกจหรือคลาสที่เราต้องการสร้างเอกสารสำหรับ
มาเปิดบรรทัดคำสั่งและไปที่ไดเรกทอรีโครงการ
สมมติว่าคลาสทั้งหมดอยู่ในโฟลเดอร์srcในไดเร็กทอรีโปรเจ็กต์:
[email protected]:~$ javadoc -d doc src\*สิ่งนี้จะสร้างเอกสารในไดเร็กทอรีที่เรียกว่าdocตามที่ระบุด้วยแฟล็ก - d หากมีหลายแพ็กเกจหรือไฟล์เราจำเป็นต้องจัดเตรียมให้ทั้งหมด
แน่นอนว่าการใช้ IDE กับฟังก์ชันในตัวนั้นง่ายกว่าและแนะนำโดยทั่วไป
3.2. Javadoc พร้อมปลั๊กอิน Maven
นอกจากนี้เรายังสามารถใช้ประโยชน์จากปลั๊กอิน Maven Javadoc:
org.apache.maven.plugins maven-javadoc-plugin 3.0.0 1.8 1.8 ... ในไดเร็กทอรีฐานของโปรเจ็กต์เรารันคำสั่งเพื่อสร้าง Javadocs ของเราไปยังไดเร็กทอรีใน target \ site:
[email protected]:~$ mvn javadoc:javadocปลั๊กอิน Maven มีประสิทธิภาพมากและอำนวยความสะดวกในการสร้างเอกสารที่ซับซ้อนได้อย่างราบรื่น
ตอนนี้เรามาดูกันว่าหน้า Javadoc ที่สร้างขึ้นมีลักษณะอย่างไร:
เราสามารถเห็นมุมมองแบบต้นไม้ของคลาสSuperHeroคลาสของเราขยายออกไป เราสามารถดูคำอธิบายช่องและวิธีการของเราและเราสามารถคลิกลิงก์เพื่อดูข้อมูลเพิ่มเติม
มุมมองโดยละเอียดของวิธีการของเรามีลักษณะดังนี้:
3.3. แท็ก Javadoc ที่กำหนดเอง
นอกเหนือจากการใช้แท็กบล็อกที่กำหนดไว้ล่วงหน้าเพื่อจัดรูปแบบเอกสารของเราแล้วเรายังสามารถสร้างแท็กบล็อกที่กำหนดเองได้อีกด้วย
In order to do so, we just need to include a -tag option to our Javadoc command line in the format of ::.
In order to create a custom tag called @location allowed anywhere, which is displayed in the “Notable Locations” header in our generated document, we need to run:
[email protected]:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*In order to use this tag, we can add it to the block section of a Javadoc comment:
/** * This is an example... * @location New York * @returns blah blah */The Maven Javadoc plugin is flexible enough to also allow definitions of our custom tags in our pom.xml.
In order to set up the same tag above for our project, we can add the following to the section of our plugin:
... location a Notable Places: ...This way allows us to specify the custom tag once, instead of specifying it every time.
4. Conclusion
บทช่วยสอนเบื้องต้นนี้ครอบคลุมถึงวิธีการเขียน Javadocs พื้นฐานและสร้างด้วยบรรทัดคำสั่ง Javadoc
วิธีที่ง่ายกว่าในการสร้างเอกสารคือการใช้ตัวเลือก IDE ในตัวหรือรวมปลั๊กอิน Maven ลงในไฟล์pom.xmlของเราและเรียกใช้คำสั่งที่เหมาะสม
ตัวอย่างโค้ดเช่นเคยสามารถพบได้บน GitHub