Có hướng dẫn về phong cách được xuất bản cho tài liệu C# XML không?

Question

Tôi yêu cầu các nhà phát triển viết mã C# để làm theo hướng dẫn của StyleCop. Nó rất tuyệt vời cho mã, nhưng tôi hầu như luôn luôn có câu hỏi về tài liệu (ok ... ok ... vì vậy không ai hỏi, bởi vì các lập trình viên có xu hướng ghét tài liệu) phong cách. Tôi có thể đề nghị sao chép phong cách của MSDN, nhưng tôi tò mò liệu Microsoft hay ai đó đã xuất bản một cái gì đó về điều này.

Ví dụ: các nhà thầu được ghi lại như sau.

/// <summary> 
/// Initializes a new instance of <c>MyClass</c> using the specified <c>BaseMyClass</c>. 
/// </summary> 
/// <param name="myParam">The <c>MyParam</c> of the current session.</param> 

Tôi không cố gắng tranh luận về cách viết tài liệu tại đây. Tôi đang tìm một số hướng dẫn được xuất bản về cú pháp được đề xuất cho tài liệu.

Cảm ơn trước!

Answer 1

StyleCop FxCop cũng thực sự cung cấp các quy tắc cho tài liệu XML. Nếu bạn không tuân theo mẫu được thiết lập bởi một bộ quy tắc nhất định, nó sẽ khiếu nại.

Đây là tất cả các quy tắc SA1600-SA1647.

Ví dụ, quy tắc SA1642: ConstructorSummaryDocumentationMustBeginWithStandardText khẳng định rằng:

Bản tóm tắt cho một constructor dụ phi tư nhân phải bắt đầu bằng “Khởi một trường hợp mới của {tên lớp} lớp.”

Để biết thêm thông tin, hãy xem FxCop.

Answer 2

Nếu bạn muốn có hướng dẫn chung về cách thức và nơi sử dụng tài liệu XML, sau đây là hai liên kết hữu ích (mà tôi đã nhắc đến nhiều lần).

• MSDN Recommended Tags for Documentation Comments
• C# XML Documentation : Alan Dean (chết - archived version)

Tôi giả định này là mơ hồ các loại điều bạn đang tìm kiếm. Về ngữ pháp thực tế và ngữ pháp của các nhận xét XML, tôi cũng đã tìm kiếm lời khuyên/hướng dẫn về điều đó, nhưng vô ích. Ý tưởng tốt nhất về khía cạnh này đơn giản là tuân theo .NET BCL (Thư viện lớp cơ sở) - mặc dù có sự mâu thuẫn kỳ lạ ngay cả trong tài liệu BCL.

Hy vọng rằng sẽ giúp ...

Answer 3

My visual studio add-in, AtomineerUtils, sẽ tạo ra và ý kiến ​​cập nhật XMLdoc.

Nó có bộ mẫu cho phép bạn chỉ định kiểu chính xác (các mục nhập hợp pháp cho các loại phần tử mã khác nhau, thứ tự chúng được liệt kê, cho dù có các dòng trống giữa các mục nhập nhất định hay không kèm theo khối tài liệu). Thao tác này sẽ xóa các mục nhập không còn chính xác (ví dụ: xóa tham số) và thêm mục nhập cho các đối tượng địa lý không có giấy tờ (ví dụ: thông số mới hoặc trường hợp ngoại lệ được ném) và nó sẽ giữ tài liệu gọn gàng bằng cách sử dụng thụt lề tự động và gói từ.

Vì vậy, bằng cách sử dụng AU để tạo và cập nhật nhận xét của bạn, bạn có thể dễ dàng thực thi một kiểu và bố cục cụ thể cho nhận xét tài liệu của mình.Nếu bạn muốn sử dụng StyleCop để thực thi một số quy tắc tài liệu, AtomineerUtils có tùy chọn để tạo tài liệu theo định dạng tương thích StyleCop.

Nó cũng làm cho nó nhanh chóng và dễ dàng để tài liệu mã mà ngay cả những lập trình viên ít sẵn sàng trong nhóm của bạn sẽ có nhiều khả năng tài liệu mã của họ tốt.