Tạo tài liệu cho code C/C++ với Doxygen

by SC

Doxygen là một công cụ mạnh dùng để sinh tài liệu từ những chú thích trong các file code, với những người lười làm doc thì doxygen đã giải quyết vấn đề document cho các developer và người quản trị dự án nói riêng một cách tuyệt vời, trong bài viết này mình sẽ dẫn cách cơ bản nhất để có thể gen doc với các source code C/C++ có sẵn

Đặc điểm của Doxygen

  • Tự động xuất document dưới dạng HTML hoặc LaTex
  • Các format như RTF(MS-Word),Postscript, Hyperlink PDF, HTML dặng nén, Unix man cũng support
  • Xuất cả document cho những code không có comment hơặc comment không theo rule nhất định
  • Xuất cả Relation fig,Include fig, Derived fig, Colaboration fig(nếu sử dụng graphvis）
  • Support cả C++, C, Java, Python, IDL, PHP, C#
  • Chạy trên Unix, Linux, Mac OSX, Windows

Các bạn có thể xem hình bên dưới để biết được mối quan hệ giữa doxygen và các thành phần khác liên quan

Để sử dụng được công cụ này thì mình xin hướng dẫn cách cơ bản, dễ hiểu và nhanh chóng nhất để mọi người có thể tiếp cận được

Cài đặt Doxygen và Graphvis

Tải file Doxygen tại www.doxygen.org

Tải file Graphvis tại http://graphviz.org

Add Graphvis vào path environment của window, ở đây mình dùng window cho nhanh chóng

Sử dụng Doxygen

Bước 1: Chọn thư mục cần tạo doxygen, cấu hình wizard như hình, ở đây mình thử tạo với thư viện C++ của RF24 dùng cho arduino tại https://github.com/nRF24/RF24

Bước 2: Chọn mode và chọn ngôn ngữ của cái bạn cần docxygen

Bước 3: Chọn Output format, HTML,XML hay latex búa xua cào cào gì đó, mình chọn HTML

Bước 4: Chọn diagram với dot tool từ Graphviz với full option

Bước 5: Qua thẻ expert cấu hình thêm một chút chỗ Dot, mặc định thì đã đủ các yêu cầu cơ bản cho chúng ta, có một số cần thêm là HAVE_DOT UML_LOOK CALL_GRAPH CALLER GRAPH, với C++ thì cần thêm CLASS_DIAGRAM

Bước 6: Vào thẻ Run chọn Run Doxygen và xuất thôi 😀

Bước 7: Xem kết quả xem sao

Bước 8: Thử với code C, các bạn làm tương tự từ bước 1 tới bước 5, bỏ chọn CLASS_DIAGRAM đi rồi run doxygen là chạy ngon lành cành mít nhé

Tạm kết

Trong bài viết này mình chỉ tập trung vào nhiệm vụ là cách sử dụng doxygen để gen ra doc từ code C/C++ có sẵn, về cách viết comment trong source code cho Doxygen cũng như những vấn đề khác thì các bạn có thể tham khảo trực tiếp từ các lib của arduino hoặc các lib của stm, hầu như họ đã viết chuẩn để xuất doxygen rồi, mình nên lấy đó làm cái tham khảo cho chuẩn. Cần thêm nữa thì các bạn có thể vào trang chủ đọc manual của doxygen là chuẩn nhất thôi.

Tham khảo

[1]