Đánh dấu "sử dụng mẫu" trong tài liệu mã số

Question

Cách thực hành tốt nhất về cách sử dụng ví dụ trong tài liệu mã là gì? Có cách nào được tiêu chuẩn hóa không? Với @usage hoặc @notes? Máy phát tài liệu có hỗ trợ điều này không?

Tôi biết câu hỏi này nên phụ thuộc vào trình tạo tài liệu. Tuy nhiên, tôi đang cố gắng để có được một thói quen sử dụng một phong cách bình luận cho thế hệ doc trước khi đi vào idiosyncrasies của mỗi máy phát điện; dường như có nhiều điểm tương đồng hơn sự khác biệt.

Tôi đã thử nghiệm với Doxygen & thường sử dụng AS3, JS, PHP, Obj-C, C++.

Ví dụ:

/** 
* My Function 
* @param object id anObject 
* @usage a code example here... 
*/ 
function foo(id) { 

} 

hoặc

/** 
* My Function 
* @param object id anObject 
* @notes a code example here, maybe? 
*/ 
function foo(id) { 

} 

Cảm ơn

Answer 1

Doxygen có một lệnh @example, và có rất nhiều lựa chọn để cấu hình đường dẫn ví dụ nguồn.

Tôi nghĩ rằng có một tập hợp chung các lệnh giữa Doxygen và các công cụ tài liệu khác, nhưng chúng quá ít để có tài liệu tốt. Bạn cần phải specilize để có được tốt nhất từ ​​một công cụ cụ thể. Tôi thích Doxygen, vì nó là mã nguồn mở và có khả năng cấu hình cao. Nhưng đó chỉ là ý kiến ​​của tôi về nó.

Có thể bạn có thể định cấu hình doxygen với @xrefitem bí danh để cho phép phân tích nhận xét tài liệu được xác định bằng các công cụ tài liệu khác.