การสร้าง Java doc ด้วย Eclipse

โดยทั่วไปแล้วในการพัฒนาโปรแกรมนั้นการมีเอกสารอ้างอิงของโปรแกรมนั้นเป็นสิ่งจำเป็นอย่างยิ่ง.  แม้ว่านักพัฒนาส่วนใหญ่จะเกลียดการทำเอกสารก็ตาม ซึ่งเอกสารเบื้องต้นของโปรแกรมนั้นเราสามารถสร้างได้โดยใช้เครื่องมือ javadoctool เพื่อสร้างเอกสาร API.  จากข้อแนะนำหรือหมายเหตุต่างๆที่เราเขียนแทรกไว้ตามโคด (comment หรือ Java doc comments).  เพราะเหตุผลดังกล่าวขั้นต้นการเขียนหมายเหตุ คำอธิบายของเมธอดต่างๆ ท้ัง ความหมาย,จุดมุ่งหมายของ input, output, exception, return และอื่นๆ จึงมีความจำเป็นอย่างยิ่ง ไม่ใช่สำหรับตัวเองเท่านั้นเพราะแน่นอนว่าไม่มีใครจำจุดประสงค์ของแต่ละเมธอดได้หมด ยิ่งเป็นการพัฒนาร่วมกับผู้อื่นยิ่งแล้วใหญ่   นั้นจึงเป็นเหตุผลในการเขียนหมายเหตุต่างๆไว้ในโคด.

ในบทความต่อไปนี้จะอธิบายวิธีการสร้างเอกสาร Javadoc สำหรับ Java project โดยใช้ Eclipse ยกตัวอย่างโคดดังต่อไปนี้.

/**
 * Connects and logins to the FTP server.
 *
 * @throws FTPConnectionException If an I/O error occurs.
 * @throws FTPLoginException If the login operation did not succeed.
 */
public void login() throws FTPConnectionException, FTPLoginException {
 
    // method body
 
}

จากตัวอย่างดังกล่าวจะเห็นว่าเมธอด login() มีการเขียนหมายเหตุไว้ (comments) ซึ่งเริ่มเท็คด้วย /** และจบแท็คด้วย */  ซึ่งจะทำให้เกิดเป็นข้อความในเอกสารใน Javadocs เป็นเอกสารที่อยู่ในรูปแบบของ HTML (in HTML format) ดังรูปต่อไปนี้:

ต่อไปนี้เรามาดูรายละเอียดการสร้างเอกสาร.  ใน Eclipse ให้เลือก Generate Javadoc… จากเมนู Project. จะมีหน้าต่าง Javadoc Generation ปรากฏขึ้นมาตามรูป:

ในหน้าต่างดังกล่าวให้ทำตามขั้นตอนต่อไปนี้ :

1. ระบุที่อยู่ของโปรแกรม javadoc ในคอมพวเตอร์ของเราโดยตัวโปรแกรมนี้จะมาพร้อมกับการติดตั้ง java JDK ของเราครับ ซึ่งที่อยู่ก็ไม่ใช่ที่ไหนครับ  เป็นที่ที่เราติดตั้งโปรแกรมนั้นเอง  เช่น  C:\Program Files\Java\jdk1.7.0_21\bin\javadoc.exe ใน Windows เป็นต้น. 
2. เลือก project และ packages ที่เราต้องการสร้างเป็นเอกสาร Javadoc ออกมา
3. เลือกไฟล์ java ที่ต้องการสร้างเอกสารโดยทั่วไปก็เลือกทั้งหมดครับ.
4. ขอบเขตของการสร้างเอกสาร Javadocs โดยเป็นการระบุว่าจะสร้างเอกสารในระดับใด ตัวอย่างเช่น : ถ้าเลือก Publicก็จะมีเพียงแต่เมธอดในระดับที่เป็น  public เท่านั้นที่จะถูกสร้างเป็นเอกสาร Javadocs  ออกมาหรือถ้าเลือกในระดับ Protected ก็จะมีเพียง protected และ public เมธอดที่จะถูกเป็นเอกสารออกมาเป็นต้น. 
5. ระบุที่อยู่ปลายทางของเอกสาร ที่ที่ซึ่งจะเก็บเอกสารเมื่อสร้างเอกสารเสร็จ. 
6. คลิก Next. 

หน้าต่างต่อมาเป็นหน้าต่างสำหรับตั้งค่าตัวเลือกต่างๆดังนี้

1. สำหรับใส่หัวข้อเอกสาร(document title)
2. ระบุโครงสร้างเอกสาร (document structure)
3. แท็คเอกสาร (documenting tags)
4. JAR files และ projects ใช้เพื่อเป็นเอกสารอ้างอิง
5. stylesheet สำหรับเอกสาร 

อย่างน้อยให้ระบุหัวข้อเอกสาร(document title)ที่เหลือปล่อยไว้ก็ได้ครับ จากนั้นคลิก  Next. 

หน้าจอต่อมาเป็นหน้าจอสำหรับตั้งค่าตัวเลือกต่างๆของ Javadoc, 

1. กำหนดเพื่อสร้างเอกสารตัวอย่าง
2. ตัวเลือกสำหรับ VM 
3. ตัวเลือกพิเศษสำหรับ javadoc
4. หากต้องการนำค่าตั้งค่าต่างๆเก็บไว้เพื่อนำกลับมาใช้อีกครั้งสามารถทำได้ โดยให้คลิกเชคที่ตัวเลือก "Save the settings of this Javadoc export as an Ant script" และระบุที่ที่จะทำการสร้างของไฟล์ Ant build. ซึ่งตัวเลือกนี้จะทำให้เราสามารถสร้าง Javadocs ใหม่ได้หลายรอบตามต้องการ 
5. ถ้าตัวเลือกที่ชื่อว่า  “Open generated index file in browser” ถูกเชคตัว  Eclipse จะทำการเปิดเอกสารที่สร้างเสร็จผ่านเว็บ browser.

คลิกปุ่ม Finish ให้รอสักครู่จนกว่าตัว Eclipse จะทำการสร้างเอกสารเสร็จ เมื่อเสร็จแล้วจะได้ตามตัวอย่าง:

หมายเหตุ: ถ้าไฟล์ Ant build ถูกสร้างเสร็จแล้ว (ในกรณีที่เราเลือกตัวเลือกว่า "Open generated index file in browser"  เราสามารถทำการรันไฟล์  Ant เพื่อสร้างเอกสาร Javadoc ได้ทุกเมื่อโดยไม่ต้องผ่าน Eclipse แต่อย่างใด.

 อ้างอิง : ที่นี่ 

About Nop

This is a short description in the author block about the author. You edit it by entering text in the "Biographical Info" field in the user admin panel.