C/C++ Doc Generator

ว่าจะอ่านเรื่องนี้มานานละ แต่ยังไม่มีโอกาส ก็พอดีว่าอยากจะใช้กับงานที่ทำอยู่ เลยได้โอกาส ก็คือเรื่องการสร้างเอกสารอัตโนมัติจาก comment ใน source code ของโปรแกรม

โปรแกรมเมอร์กับเอกสารมักเป็นไม้เบื่อไม้เมากัน แต่ถ้าเขียนโปรแกรมโดยใส่ comment ให้เป็นระเบียบล่ะก็ ไม่เหลือบ่ากว่าแรง แถมถ้ามีเครื่องมือดึงเอา comment เหล่านั้นออกมา สร้างเป็น reference manual ได้เลย ก็ยิ่งแจ๋ว ตามคอนเซ็ปต์ Literate Programming ของท่านปรมาจารย์ Knuth ซึ่งเอกสารนี้ ค่อนข้างจำเป็นเป็นพิเศษสำหรับโค้ดที่เป็น library เพื่อให้ผู้ใช้ไลบรารีใช้เป็นคู่มือสร้างโปรแกรมได้

ภาษา Java จะกำหนดรูปแบบ comment พิเศษสำหรับการสร้างเอกสารด้วย Javadoc มาใน syntax ของภาษาเลย

/// ...
/** ... */

ส่วนภาษา C/C++ ก็จะใช้โปรแกรม documentation generator ซึ่งจะกำหนดรูปแบบของ comment ในลักษณะเดียวกัน เพื่อใช้สร้างเอกสารโดยเฉพาะ ตัวที่เคยได้ยินคุ้นหูจะมีสองตัว คือ Doxygen กับ DOC++ ซึ่ง DOC++ นั้น เก่ามากแล้ว รูปแบบเอกสารที่ได้ จึงดูอยู่คนละยุคกับ ของ Doxygen และหลายโครงการที่ เคยใช้ DOC++ ก็เปลี่ยนมาใช้ Doxygen กันเยอะแล้ว แบบนี้ คงตัดสินใจไม่ยากละ

เริ่มจากลง Doxygen ก่อนเลย (สำหรับ Debian)

# apt-get install doxygen

โดยอาจจะลง doxygen-doc และ doxygen-gui เพิ่มด้วย ตัวแรกเอาไว้อ่านวิธีใช้ ตัวหลังเอาไว้สร้าง config file เริ่มแรกแบบอัตโนมัติ

Doxygen จะใช้ config file ชื่อ Doxyfile ซึ่งกำหนดรูปแบบของเอกสารที่จะสร้าง ในนั้นจะมีรูปแบบเป็นการกำหนดค่าตัวแปรต่างๆ ซึ่งอ่าน เอกสาร แล้ว อาจธาตุไฟเข้าแทรกได้ อย่ากระนั้นเลย เราสร้างด้วยเครื่องมืออัตโนมัติดีกว่า:

$ doxywizard

แล้วก็ทำไปตามขั้นตอนของเขา ก็จะได้ output เปล่าๆ จาก C/C++ source ออกมาเลย หรือถ้าทำ comment รอไว้แล้ว ก็จะได้เนื้อเอกสารออกมาด้วย

สร้าง config file แล้ว ขั้นต่อไปก็คือ การใส่ comment ก็อาจจะใช้รูปแบบนี้ สำหรับโค้ด C++ (โดยใน config file ไม่ได้เปิดใช้ JAVADOC_AUTOBRIEF):

/// Brief description.
/**
 * Long description.
 * @param x : x description
 * @param y : y description
 */
void ClassName::method (int x, int y)
{
  // ...
}

หรือถ้าเป็นภาษา C ซึ่งไม่ได้มีคลาส แต่ใช้ global function เป็นหลัก ก็ต้องระบุว่าจะทำ document ของ file ก่อน:

/** @file hello.h */

void hello (const char* name);

แล้วไปเขียน doc ที่ตัวฟังก์ชัน (.c):

/**
 * Descriptions.
 * @param name : name description
 */
void hello (const char* name)
{ 
  /* ... */
}

พอใส่ comment เสร็จก็สั่ง:

$ doxygen

แล้วดูผลลัพธ์ตามที่ได้ config ไว้

ใครบอกผมก่อนหน้านี้นะ ว่าอยากใช้ doxygen กับ libthai? เดี๋ยวจัดให้.. (รอว่างก่อน)