Tài liệu tập tin tiêu đề C/C++

Question

Bạn nghĩ cách nào là thực hành tốt nhất khi tạo tệp tiêu đề công khai trong C++?

1. Tệp tiêu đề có nên chứa tài liệu không, tóm tắt hoặc lớn không? Tôi đã thấy mọi thứ từ hầu như không có tài liệu nào (dựa vào một số tài liệu bên ngoài) cho các thông số lớn về các biến thể, các tham số hợp lệ, các giá trị trả lại, v.v. Tôi không chắc chính xác những gì tôi thích, tài liệu lớn là tốt vì bạn luôn truy cập nó từ trình soạn thảo của bạn, mặt khác một tập tin tiêu đề với tài liệu rất ngắn gọn thường có thể hiển thị một giao diện hoàn chỉnh trên một hoặc hai trang văn bản cho một cái nhìn tổng quan tốt hơn về những gì có thể làm với một lớp.

2. Giả sử tôi sử dụng tài liệu ngắn hoặc lớn. Tôi muốn một cái gì đó tương tự như javadoc, nơi tôi tài liệu giá trị trả lại, các tham số, vv Các quy ước tốt nhất cho rằng trong c + + là gì? Theo như tôi có thể nhớ doxygen làm công cụ tốt với tài liệu kiểu tài liệu java, nhưng có bất kỳ công ước và công cụ nào khác cho điều này tôi cần phải nhận thức được trước khi đi cho tài liệu phong cách javadoc?

Answer 1

Thông thường tôi đưa tài liệu cho giao diện (thông số, giá trị trả về, gì chức năng thực hiện) trong file giao diện (.h), và các tài liệu hướng dẫn để thực hiện (cách chức năng thực hiện) trong việc thực hiện tệp (.c, .cpp, .m).

Tôi viết tổng quan về lớp ngay trước khi khai báo, vì vậy người đọc có thông tin cơ bản ngay lập tức.

Công cụ tôi sử dụng là Doxygen.

Answer 2

1. tôi sẽ definetely có một số tài liệu trong phần đầu tập tin bản thân. Nó cải thiện đáng kể việc gỡ lỗi để có thông tin bên cạnh mã, chứ không phải trong các tài liệu riêng biệt. Theo quy tắc chung, tôi sẽ ghi lại API (giá trị trả về, đối số, thay đổi trạng thái, v.v.) bên cạnh mã và tổng quan kiến ​​trúc cấp cao trong các tài liệu riêng biệt (để cung cấp cái nhìn rộng hơn về cách mọi thứ được đặt cùng nhau; khó có thể đặt mã này cùng với mã, vì nó thường tham chiếu nhiều lớp cùng một lúc).

2. Doxygen tốt cho kinh nghiệm của tôi.

Answer 3

Đặt đủ mã mà bạn có thể đứng một mình. Gần như mọi dự án tôi đã ở nơi tài liệu được tách biệt, nó đã lỗi thời hoặc không được thực hiện, một phần rằng nếu đó là một tài liệu riêng biệt, nó trở thành một nhiệm vụ riêng biệt, một phần do quản lý không cho phép nó như một nhiệm vụ trong việc bù đắp. Việc ghi lại nội tuyến là một phần của luồng hoạt động tốt hơn nhiều trong trải nghiệm của tôi.

Viết tài liệu ở dạng mà hầu hết người chỉnh sửa nhận ra là một khối; cho C++ này có vẻ là/* chứ không phải là //. Bằng cách đó bạn có thể gấp nó và chỉ nhìn thấy các tờ khai.

Answer 4

Có thể bạn sẽ quan tâm đến gtk-doc. Nó có thể là "một chút vụng về để cài đặt và sử dụng" nhưng bạn có thể có được một tài liệu API đẹp từ mã nguồn, nhìn như thế này:

String Utility Functions

Answer 5

Tôi tin Doxygen là nền tảng phổ biến nhất để tạo ra các tài liệu, và theo như tôi biết, nó ít nhiều có thể bao gồm ký hiệu JavaDoc (không giới hạn trong khóa học).Tôi đã sử dụng doxygen cho C, với kết quả OK, tôi nghĩ rằng nó phù hợp hơn cho C + + mặc dù. Bạn có thể muốn nhìn vào robodoc là tốt, mặc dù tôi nghĩ rằng dao cạo Occam sẽ cho bạn biết để thay vì đi cho Doxygen.

Về số lượng tài liệu, tôi chưa bao giờ là người viết tài liệu, nhưng tôi có thích hay không, có nhiều tài liệu hơn luôn bị đánh bại khi không có tài liệu. Tôi muốn đặt tài liệu API trong tệp tiêu đề và tài liệu triển khai trong triển khai (viết tắt là lý do, phải không?). :) Bằng cách đó, các IDE có cơ hội để lấy nó và hiển thị nó trong khi tự động hoàn thành (Eclipse thực hiện điều này cho JavaDocs, ví dụ, có lẽ cũng cho doxygen?), Mà không nên đánh giá thấp. JavaDoc có thêm quirk rằng nó sử dụng câu đầu tiên (tức là đến điểm dừng đầu tiên) như một mô tả ngắn gọn, không biết liệu Doxygen có thực hiện điều này hay không, nhưng nếu có, nó cần được xem xét khi viết tài liệu.

Có rất nhiều tài liệu có nguy cơ bị lỗi thời, việc giữ tài liệu gần với mã sẽ giúp mọi người có cơ hội cập nhật mã, vì vậy bạn nên giữ nó trong nguồn/tiêu đề các tập tin. Điều không nên quên là việc sản xuất tài liệu. Có, một số người sẽ sử dụng tài liệu trực tiếp (thông qua IDE hoặc bất kỳ thứ gì, hoặc chỉ đọc tệp tiêu đề), nhưng một số người thích các cách khác, vì vậy bạn nên xem xét đặt tài liệu API (cập nhật thường xuyên) trực tuyến, tất cả đều đẹp và có thể xem , cũng như có thể sản xuất các tệp người dùng nếu bạn đang nhắm mục tiêu * các nhà phát triển dựa trên nix.

Đó là hai xu của tôi.