Vietnamen’s Weblog

Time, Chances, Diligence, Intelligence: which is the most important?

Doxymacs – generate code documentation in emacs

leave a comment »

Doxymacs là sự kết hợp giữa Doxygen + {X}Emacs.

Doxygen là tool giúp trích xuất thông tin của source code thành dạng documentation giúp cho việc tra cứu tham khảo sử dụng các hàm dễ dàng. Các tool khác: JavaDoc, GTK-Doc… Yêu cầu của các tool này là comment được viết theo một qui luật định sẵn để chúng có thể trích xuất thông tin ra dễ dàng.

Emacs lại là một IDE rất mạnh và hữu ích.

Trong Ubuntu, các package này đều có sẵn

sudo aptitude

tìm kiếm doxymacs, doxygen, doxygen gui và install 3 packages này. Có thể install thêm doxygen-doc nếu muốn.

Sau đó, thêm vào file ~/.emacs

(add-hook 'c-mode-common-hook
  (lambda ()
    (require 'doxymacs)
    (doxymacs-mode t)
    (doxymacs-font-lock)))

Tuỳ vào programming language khác nhau mà cấu trúc của comment thay đổi (minh hoạ ở dưới). Tuy nhiên, để đơn giản, doxymacs cung cấp một số iteractive function

doxymacs-insert-function-comment

doxymacs-insert-file-comment  --> C-c d i

Những thức cần có khi comment một subprogram

  1. thông tin về thông số đầu vào (type, optional, in/out/inout…)
  2. thông tin về return value (type), exception gì, có cần phải free (deallocate) hay không

Comment có thể đặt ngay tại header files (.h) hoặc nơi implementation (.c/.cpp). Điều này là tuỳ ý thích mỗi người. Đối với một số ngôn ngữ, ví dụ Fortran, không có header file nên comment chỉ có ở trong implementation file.

C language

/** 
 *
 *
 * @param a
 * @param b
 *
 * @return
 */
int frobnicate_numbers (int a, int b);

Fortran

References:

  1. http://doxymacs.sourceforge.net/
  2. http://emacs-fu.blogspot.com/2009/01/commenting-your-functions.html
  3. http://www.digitalpeer.com/id/emacs
  4. http://www.lrde.epita.fr/cgi-bin/twiki/view/Projects/EmacsTricks
  5. http://www.stack.nl/~dimitri/doxygen/helpers.html
  6. Fortran patch: http://sourceforge.net/forum/message.php?msg_id=7442794
  7. http://www.stack.nl/~dimitri/doxygen/starting.html

Written by vietnamen

Tháng Bảy 28, 2009 lúc 12:49 chiều

Gửi phản hồi

Mời bạn điền thông tin vào ô dưới đây hoặc kích vào một biểu tượng để đăng nhập:

WordPress.com Logo

Bạn đang bình luận bằng tài khoản WordPress.com Log Out / Thay đổi )

Twitter picture

Bạn đang bình luận bằng tài khoản Twitter Log Out / Thay đổi )

Facebook photo

Bạn đang bình luận bằng tài khoản Facebook Log Out / Thay đổi )

Google+ photo

Bạn đang bình luận bằng tài khoản Google+ Log Out / Thay đổi )

Connecting to %s

%d bloggers like this: