C ++: Tạo tài liệu với Doxygen - núm vú

Hầu hết các lập trình ghét tạo tài liệu thậm chí nhiều hơn họ ghét nhận xét về mã của riêng họ. Nhập Doxygen, cho phép các lập trình nhúng các thẻ trong các nhận xét sau này có thể được trích xuất để tạo ra tài liệu.

Cài đặt Doxygen

Doxygen không đi kèm với Mã số:: Các khối (ít nhất không phải là của văn bản này). Bạn sẽ cần phải tải về phiên bản Doxygen thích hợp cho ứng dụng của bạn. Sau khi bạn liên kết tới trang web Doxygenorg, bạn có thể điều hướng đến trang tải về và tìm phiên bản Doxygen cho hệ điều hành của bạn, như thể hiện ở đây:

Tải xuống và cài đặt phiên bản phù hợp với hệ điều hành của bạn. Bạn có thể chấp nhận mặc định, nhưng hãy nhớ nơi mà trình hướng dẫn cài đặt đặt tập tin thực thi Doxygen.

Bây giờ bắt đầu Mã số:: Blocks. Chọn DoxyBlocks → Mở Preferences. Từ đó chọn tab General và thiết lập Path to Doxygen. (Đây là đường dẫn mà bạn đã lưu ý ở đoạn trước). Đường dẫn mặc định cho Windows là C: Program Filesdoxygenbindoxygen. exe. Làm tương tự cho Đường dẫn Doxywizard. Đây là mặc định cho Windows là C: Chương trình Filesdoxygenbindoxywizard. exe . Bạn có thể bỏ trống các công cụ khác vì không cần thiết khi tạo tài liệu ở định dạng HTML.

/ **

bình luận, đó là tốt. (Bạn có thể thay đổi kiểu bình luận cho một trong những người khác bằng cách chọn DoxyBlocks → Open Preferences và sau đó chọn tab Style Nhận xét)

Để xem cách hoạt động của nó, đặt con trỏ vào đầu của một hàm và chọn DoxyBlocks → Block Comment (hoặc nhấn Ctrl + Alt + B). Một nhận xét như sau xuất hiện (các ví dụ sau đang sử dụng chương trình Budget5 xuất hiện trong tài liệu có thể tải xuống tại www. Dummies. Com / extras / cplusplus):

/ ** ngắn * * param danh sách accList & * return void * * / void getAccounts (list & accList) {

Mã:: Khối chèn một chú giải Doxygen block bắt đầu từ

/ **.

Doxygen biết rằng chú thích này thuộc về định nghĩa hàm mà ngay sau đó. Doxygen từ khóa bắt đầu với dấu gạch chéo ngược (). Thẻ từ khóa ngắn mô tả ngắn gọn về chức năng. Mô tả ngắn gọn có thể kéo dài trên nhiều hơn một dòng.Đây phải là một mô tả ngắn về chức năng xuất hiện trong các bảng hiển thị dạng bảng. Lập trình viên có thể làm theo điều này với mô tả kỹ lưỡng hơn gắn với từ khóa chi tiết

. Mô tả chi tiết này cho phép mô tả kỹ hơn về chức năng của hàm. Nhiều từ khóa Doxygen là tùy chọn. Cụ thể, từ khóa chi tiết

được giả định nếu bạn bắt đầu một đoạn văn tách khỏi mô tả ngắn bằng dòng lệnh trống. Vượt ra ngoài đó là một dòng riêng biệt được gắn cờ với từ khóa param

để mô tả từng đối số cho hàm. Cuối cùng, từ khóa return mô tả giá trị trả về bởi hàm. getAccounts () có thể xuất hiện như sau:

/ ** ngắn getAccounts - Nhập tài khoản từ bàn phím * Chi tiết Chức năng này đọc dữ liệu nhập vào từ bàn phím. * Đối với mỗi S hoặc C nhập, chức năng tạo ra một mới * tiết kiệm hoặc kiểm tra đối tượng tài khoản và thêm nó vào danh sách tài khoản *. Một X chấm dứt mục nhập. Bất kỳ đầu vào nào khác * được giả định là một khoản tiền gửi (số lớn hơn * 0) hoặc số rút tiền (số ít hơn 0). * * param danh sách accList và danh sách các tài khoản * các đối tượng được tạo bởi getAccounts () * return void * / void getAccounts (list & accList) { Bạn cũng có thể thêm một bình luận Doxygen trên cùng một dòng. Điều này thường được sử dụng khi bình luận các thành viên dữ liệu. Đặt con trỏ vào cuối dòng và chọn DoxyBlocks → Line Comment hoặc nhấn Ctrl + Alt + L. Bây giờ điền vào một mô tả của các thành viên dữ liệu. Kết quả xuất hiện như trong ví dụ sau đây cũng lấy từ Ngân sách5: cân bằng đôi; / **

Tạo Tài liệu Doxygen Doxygen

Doxygen có thể tạo tài liệu bằng nhiều định dạng khác nhau, mặc dù một số (chẳng hạn như HTML biên soạn) yêu cầu tải thêm. Các định dạng HTML đặc biệt thuận tiện vì nó không đòi hỏi gì nhiều hơn một trình duyệt để xem.

Mặc định là HTML, nhưng nếu bạn muốn thay đổi định dạng, chọn DoxyBlocks → Open Preferences, sau đó chọn tab Doxyfile Defaults 2. Trong cửa sổ này bạn có thể chọn tất cả các định dạng khác nhau mà bạn muốn tạo ra.

Trước khi trích xuất tài liệu lần đầu tiên, có thể bạn sẽ muốn chọn một vài tùy chọn khác. Chọn DoxyBlocks → Open Preferences, và sau đó chọn tab Doxyfile Defaults. Đảm bảo hộp kiểm Extract All được chọn. Tiếp theo chọn tab Doxyfile Defaults 2 và kiểm tra hộp kiểm Class_Diagrams. Bây giờ hãy chọn tab General và kiểm tra hộp Run HTML After Compilation. Nhấp OK, và bạn đã hoàn tất. (Bạn sẽ không cần phải làm lại điều này vì các tùy chọn được lưu trong một tệp gọi là doxyfile.)

Chọn DoxyBlocks → Trích xuất tài liệu để tạo và xem tài liệu. Sau một khoảng thời gian khá ngắn, Doxygen mở trình duyệt yêu thích của bạn với các tài liệu như thể hiện trong hình dưới đây.

Doxygen không phải là rất thân thiện với người sử dụng khi nói đến lỗi đầu vào. Đôi khi Doxygen chỉ ngừng sản xuất tài liệu tại một số điểm trong nguồn của bạn vì không có lý do rõ ràng.Kiểm tra doxygen. log chứa trong cùng một thư mục với tệp doxyfile cho bất kỳ lỗi nào có thể đã xảy ra trong quá trình trích xuất.

Hình dưới đây cho thấy trình duyệt dự án trong cửa sổ bên trái cho phép người dùng điều hướng trong tài liệu của dự án. Ở bên phải, hàm getAccounts () đã được chọn để có được mô tả chi tiết hơn. Mô tả ngắn gọn xuất hiện trên dòng đầu tiên, tiếp theo là mô tả chi tiết, các tham số, và giá trị trả về:

Tài liệu của lớp tương tự như được trình bày bởi đoạn mã sau đây.

/ ** class Tài khoản * tóm tắt một tài khoản ngân hàng trừu tượng. * chi tiết Lớp trừu tượng này kết hợp các tính chất * cùng với cả hai loại tài khoản: Kiểm tra và Tiết kiệm. Tuy nhiên, nó thiếu khái niệm rút tiền (), khác giữa hai * Tài khoản lớp (Tài liệu cho

Tài khoản

được hiển thị ở đây:

Chú ý mô tả xuất hiện bên dưới lớp Tài khoản .

Đây là mô tả ngắn gọn. Nhấp vào Thêm sẽ đưa bạn đến phần mô tả chi tiết. Cũng lưu ý biểu đồ đồ họa của mối quan hệ thừa kế giữa Tài khoản , các lớp cha mẹ của nó và các lớp con của nó.