Tài liệu XML Nhận xét với Giao diện và thực hiện các lớp học

Question

Tôi đang tạo tài liệu cho một assembly bằng cách sử dụng XML Documentation Comments, từ đó tệp chm sẽ được tạo bằng cách sử dụng Sandcastle.

Hội đồng của tôi chứa các giao diện khác nhau, mỗi giao diện được thực hiện bởi một lớp (trong kịch bản của tôi đây là các dịch vụ WCF).

Tôi đã thêm tài liệu vào giao diện, có cách nào để tôi tự động ghi lại các phương pháp có liên quan trên các lớp triển khai không?

Answer 1

Dường như không có bất kỳ hỗ trợ nào cho việc tự động hóa tài liệu đó ở Sandcastle. Sandcastle Help File Builder mặc dù triển khai thẻ inheritdoc tùy chỉnh.

Từ trang web SHFB:

Hỗ trợ được bao gồm cho < inheritdoc/> thẻ cho phép bạn tài liệu kế thừa từ cơ sở loại/thành viên. Điều này được triển khai thông qua một công cụ độc lập để nó cũng có thể là được sử dụng bởi các công cụ của bên thứ ba khác và tạo tập lệnh. Công cụ này cung cấp các tính năng ngoài những tính năng được tìm thấy trong thành phần xây dựng được cung cấp với Lâu đài cát.

Cập nhật Thứ hai: theo this workitem, các Sandcastle "hỗ trợ" cho inheritdoc là thông qua các công cụ SHFB. Tóm lại, tôi giả sử là, SHFB giải quyết vấn đề của bạn.

Answer 2

Công cụ như GhostDoc có thể tạo tài liệu về các lớp triển khai khi bạn sử dụng phím tắt trên bàn phím. Đó không phải là hoàn toàn tự động, nhưng có thể giúp ngăn chặn quá nhiều bản sao chép.

Có lẽ nó có thể được tự động hóa bằng tập lệnh.

Answer 3

AtomineerUtils sẽ tự động tạo nhận xét cho bạn và nhận tài liệu hiện có từ quá tải và lớp cơ sở bị ghi đè, giúp bạn tiết kiệm rất nhiều rắc rối khi sao chép thông tin cần thiết.

http://www.atomineer.com/AtomineerUtils.html

Answer 4

Tôi có một câu trả lời tốt hơn: FiXml.

comments Nhân bản với GhostDoc \ AtomineerUtils chắc chắn là phương pháp làm việc, nhưng nó có nhược điểm đáng kể, ví dụ .:

• Khi nhận xét ban đầu được thay đổi (mà thường xuyên xảy ra trong phát triển), clone của nó không phải là.
• Bạn đang tạo số lượng bản sao khổng lồ. Nếu bạn đang sử dụng bất kỳ công cụ phân tích mã nguồn nào (ví dụ: Công cụ tìm kiếm trùng lặp trong Thành phố nhóm), nó sẽ tìm chủ yếu nhận xét của bạn.

Vì nó đã được đề cập, có <inheritdoc> thẻ trong Sandcastle, nhưng nó có vài nhược điểm so với FiXml:

• Sandcastle tạo tập tin trợ giúp HTML biên soạn - nó không sửa đổi .xml file chứa các nhận xét XML được trích xuất. Nhưng các tệp này được nhiều công cụ sử dụng, bao gồm .NET Reflector và trình duyệt lớp \ IntelliSense trong Visual Studio .NET. Vì vậy, nếu bạn chỉ sử dụng Sandcastle, bạn sẽ không thấy tài liệu được thừa hưởng ở đó.
• Triển khai của Sandcastle ít mạnh mẽ hơn. Ví dụ. không có số <see ... copy="true" />.

Xem Sandcastle's <inheritdoc> description để biết thêm chi tiết.

Mô tả ngắn về FiXml: nó là một bộ xử lý sau của tài liệu XML được tạo bởi C# \ Visual Basic .Net. Nó được thực hiện như nhiệm vụ MSBuild, vì vậy nó khá dễ dàng để tích hợp nó vào bất kỳ dự án nào. Nó giải quyết một vài trường hợp khó chịu liên quan đến việc viết tài liệu XML bằng các ngôn ngữ sau:

• Không hỗ trợ kế thừa tài liệu từ lớp cơ sở hoặc giao diện. I.e. một tài liệu cho bất kỳ thành viên bị ghi đè nào phải được viết từ đầu, mặc dù thông thường là khá mong muốn thừa hưởng ít nhất một phần của nó.
• Không hỗ trợ chèn các mẫu tài liệu thường được sử dụng, chẳng hạn như “Đây là loại là singleton -. Sử dụng tài sản <see cref="Instance" /> của nó để có được những trường hợp duy nhất của nó”, hay thậm chí là “Khởi một trường hợp mới của <CurrentType> lớp.”

Để giải quyết vấn đề nêu trên, các thẻ XML bổ sung sau đây được cung cấp:

• <inheritdoc />, <inherited /> thẻ
• <see cref="..." copy="..." /> attrib ute trong thẻ <see/>.

Đây là its web page và download page.