ลืม javaDoc, phpDoc, jsDoc ไป มาใช้ Natural Docs ดีกว่า
document generator เป็นแนวคิดในการสร้างเอกสารประกอบโปรแกรม (API, Manual document) แบบอัตโนมัติ ซึ่งเอกสารนี้ถูกสร้างขึ้นด้วยข้อมูลต่างๆ ที่อยู่ใน source code ซึ่งมักจะใช้ syntax เฉพาะ ยกตัวอย่างเช่น
javaDoc ต้นตำหรับเลยมั่งนี่
jsDoc เขียนด้วย PERL แต่ติดปัญหาข้างต้น นอกจากมี tools อีกตัว พัฒนาด้วย java (jar) ขื่อว่า jsdoc-toolkit
scriptDoc จาก Aptana ไม่ค่อยแพร่หลาย ใช้กับ Aptana IDE
phpDoc อันนี้ ถอดมาจาก javaDoc เลย
เรื่องมีอยู่ว่า ผมจะนำเอา jsDoc มาใช้กับ javascript api library ตัวหนึ่ง แต่บังเอิญว่า pattern ของ Prototype.js ซึ่งใ้ช้งานลักษณะตามด้านล่างนี้ ใ้ช้ไม่ได้
var Person = Class.create({
initialize: function(name) {
this.name = name;
},
say: function(message) {
return this.name + ': ' + message;
}
});
ปัญหาก็คือ jsDoc ไม่รู้จักรูปแบบ say: function(message) ทำอย่างไรดีหว่า??
ตอนแรกคิดว่าคงต้องปรับปรุง หรือเขียน parser เองซะแล้ว แต่โชคดีเป็นที่สุดบังเอิญเจอโครงการ Natural Docs
Natural Docs พัฒนาโดยคุณ Greg Valure ใ้ช้ภาษา PERL เป็น Opensource ภายใต้ GNU General Public License
ข้อดีข้อ Natural Docs คือ ไม่ขึ้นกับภาษา Parser ของ phpdoc, javadoc, jsdoc นั้นไม่จำเป็นต้องระบุชื่อ class, method แต่นั่นทำให้มีข้อจำกัดในการผูกติดกับภาษา (ถึงแม้ว่าหลายๆ ตัวแทบจะไม่ต่างกันเลย เช่น phpdoc, javadoc) สำหรับ Natural Docs เราอาจต้องออกแรงหน่อย ในการระบุชื่อ class, method ลงไปใน source code เอง
อันที่จริงแนวคิดของ Natural Docs นั้นง่ายมาก มันไม่สนใจหรอกครับว่า โปรแกรมของเราเขียนด้วยภาษาอะไร โปรแกรมจะเข้าไปยังไฟล์ต่างๆ แล้วมองหา pattern ตามรูปแบบที่กำหนด
ยกตัวอย่างรูปแบบของ Natural Docs
/*
* Function: Multiply
*
* Multiplies two integers.
*
* Parameters:
* x - The first integer.
* y - The second integer.
*
* Returns:
* The two integers multiplied together.
*
* See Also:
* <Divide>
*/
int Multiply (int x, int y)
{ return x * y; };
เทียบกับ javaDoc
/**
* Multiplies two integers.
*
* @param x The first integer.
* @param y The second integer.
* @return The two integers multiplied together.
* @see Divide
*/
int Multiply (int x, int y)
{ return x * y; };
* อันที่จริง Natural Docs ก็ support javaDoc syntax ด้วยนะ :) และก็ค่อนข้างเป็นที่นิยมในกลุ่มนักพัฒนา Flex (ถึงแม้ว่า Adobe จะมี ASDoc ก็เหอะ)
ตัวอย่างโครงการที่ใ้ช้ Natural Docs
นอกจากนี้แล้วมีอีกตัวที่น่าสนใจคือ ROBODoc ดูความสามารถแล้ว ออกจะดีกว่า Natural Docs ด้วยซ้ำ พอดีเพิ่งมาเจอ เลยไม่ได้ใช้
จริงๆ แล้วโปรแกรมประเภท document generator นั้นมีเยอะมาก ลองดู Wikipedia: Comparison of documentation generators
Links
ความเห็น (0)
ไม่มีความเห็น