Có một tiêu chuẩn (như phpdoc hoặc python's docstring) để bình luận mã C#?

Question

Có quy ước chuẩn nào (như phpdoc hay docstring của python) để bình luận mã C# để tài liệu lớp có thể được tạo tự động từ mã nguồn không?

Answer 1

Bạn có thể sử dụng nhận xét kiểu XML và sử dụng các công cụ để đưa các nhận xét đó vào tài liệu API.

Dưới đây là một ví dụ về phong cách bình luận:

/// <summary> 
/// Authenticates a user based on a username and password. 
/// </summary> 
/// <param name="username">The username.</param> 
/// <param name="password">The password.</param> 
/// <returns> 
/// True, if authentication is successful, otherwise False. 
/// </returns> 
/// <remarks> 
/// For use with local systems 
/// </remarks> 
public override bool Authenticate(string username, string password) 

Một số mặt hàng để tạo điều kiện này là:

GhostDoc, trong đó cung cấp một phím tắt duy nhất để tự động tạo ra cảm nhận cho một lớp hoặc phương pháp. Sandcastle, tạo tài liệu kiểu MSDN từ nhận xét XML.

Answer 2

/// <summary> 
/// 
/// </summary> 
/// <param name="strFilePath"></param> 

http://msdn.microsoft.com/en-us/magazine/cc302121.aspx

Answer 3

C# đã xây dựng trong documentation commands Hãy vui vẻ!

Answer 4

Microsoft sử dụng "XML Documentation Comments" sẽ cung cấp mô tả intellisense IDE và cũng cho phép bạn tự động tạo tài liệu kiểu MSDN bằng công cụ như Sandcastle nếu bạn bật tính năng tạo tệp XML.

Để bật tính năng tạo tệp XML cho tài liệu, hãy nhấp chuột phải vào dự án trong studio trực quan, nhấp vào "Thuộc tính" và chuyển đến tab "Xây dựng". Về phía dưới cùng, bạn có thể chỉ định một vị trí cho tệp đầu ra nhận xét XML của bạn.

Answer 5

Các câu trả lời trước chỉ ra cú pháp XML một cách hoàn hảo. Tôi chỉ muốn đưa ra đề xuất của tôi cho free (and open-source) nDoc help library generator để phân tích tất cả các nhận xét trong một dự án.

Answer 6

Tôi luôn được yêu cầu sử dụng các nhận xét chặn mở với 2 hoặc nhiều dấu hoa thị để phân định các nhận xét tài liệu.

/** 
Documentation goes here. 
(flowerboxes optional) 
*/