Theppitak's blog

My personal blog.

09 ตุลาคม 2548

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

doxywizard screenshot

แล้วก็ทำไปตามขั้นตอนของเขา ก็จะได้ 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? เดี๋ยวจัดให้.. (รอว่างก่อน)

2 ความเห็น:

  • 10 ตุลาคม 2548 02:46 , Blogger id แถลง…

    why doesn't gtk+ use doxygen? what's the advantage of gtk-doc over doxygen? (honest)

     
  • 10 ตุลาคม 2548 09:15 , Blogger Thep แถลง…

    yeh, ลืมเขียนถึง gtk-doc เลย (จริงๆ มันก็ยาวแล้วแหละ ถ้าจะเขียน ก็น่าจะเป็นตอนใหม่ไปเลย)

    gtk-doc มันมาครบเซ็ต พร้อม m4 macro สำหรับใช้กับ autoconf และคำสั่ง gtkdocize สำหรับเริ่มต้นระบบ build โดยอัตโนมัติ แล้วก็รองรับ feature ของ gobject เช่น การ document signal ต่างๆ ด้วย

    ในขณะที่ doxygen มันออกแบบมาให้เหมาะกับ C++ มากกว่า C คือถ้า project คุณใช้ GTK+ หรือ GObject แล้วใช้ doxygen จะต้องทำอะไรเพิ่มอีกพอสมควร ถ้าเทียบกับใช้ gtk-doc ทั้งนี้ ยังไม่นับรวมความเข้าเซ็ตกับระบบ documentation ของ GNOME

    นอกจาก gtk-doc แล้ว GNOME มี gnome-doc-utils ซึ่งช่วยทำระบบ build ให้สร้างเอกสารใน project ได้ทันที บวกกับ DocBook XSLT stylesheet ที่ทำให้เอกสารมีหน้าตาเข้าชุดกัน แล้วก็ xml2po ที่ช่วยแปลเอกสารอื่นๆ ที่ไม่ใช่การ extract จาก source (เช่น คู่มือผู้ใช้ที่เขียนด้วย DocBook) ผ่าน PO file ด้วย

     

แสดงความเห็น (มีการกลั่นกรองสำหรับ blog ที่เก่ากว่า 14 วัน)

<< กลับหน้าแรก

hacker emblem