Có cách nào để tham khảo các nhận xét xml để tránh sao chép chúng không?

Question

Đây không phải là một vấn đề lớn, nhưng cái gì đó sẽ rất hữu ích thực sự nếu được giải quyết.

Khi tôi đang quá tải phương pháp vv có lần khi các bình luận xml là chính xác giống nhau, thanh 1 hoặc 2 tên param. Tôi phải sao chép/dán các chú thích xuống từng phương thức quá tải, nơi chúng giống nhau. Đôi khi, tuy nhiên, điều này có thể gây ra thông tin gây hiểu lầm về phương pháp nếu tôi cập nhật một trong số họ và quên quay lại và sao chép/dán chúng vào tất cả những người khác. Nếu có rất nhiều phương pháp quá tải, điều này có thể rất tốn thời gian và dễ bị lỗi.

Vì vậy, tôi tự hỏi liệu có cách lưu trữ nhận xét ở một nơi (như biến), mà tôi có thể chỉ đơn giản là tham chiếu thay thế. Bằng cách này, một thay đổi sẽ được phản ánh trên tất cả các khoản tiền liên quan.

Dưới đây là một ví dụ:

/// <summary> 
    /// Go and do something 
    /// </summary> 
    public void DoSomething() 
    { 
     DoSomething(true, "Done something"); 
    } 

    /// <summary> 
    /// Go and do something 
    /// </summary> 
    /// <param name="doIt">whether it should be done or not</param> 
    public void DoSomething(bool doIt) 
    { 
     DoSomething(doIt, "Done something"); 
    } 

    /// <summary> 
    /// Go and do something cool 
    /// </summary> 
    /// <param name="doIt">whether it should be done or not</param> 
    /// <param name="doneMessage">message to show once done</param> 
    public void DoSomething(bool doIt, string doneMessage) 
    { 
     if (doIt) 
      Console.WriteLine(doneMessage); 
    } 

Như bạn có thể thấy, tất cả các ý kiến ​​đều giống nhau ngoại trừ tôi quyết định làm một sự điều chỉnh trên người cuối cùng để đọc 'hãy đi và làm một cái gì đó mát mẻ'. Bây giờ tôi sẽ phải đi và thay đổi này là tất cả các ý kiến ​​phương pháp khác quá.

Chúc mừng.

Answer 1

Theo các thông số kỹ thuật:

http://msdn.microsoft.com/en-us/library/5ast78ax.aspx

Không có tiêu chuẩn thiết lập để lấy ý kiến ​​XML; những cái được hiển thị trên trang đó chỉ là "được khuyến nghị". Trong các thẻ được đề xuất, không có tính năng như vậy. Tuy nhiên, công cụ tài liệu XML vui vẻ chấp nhận những điều sau đây mà không có cảnh báo:

/// <summary id="30">foo</summary> 
void bar(); 

/// <summary id="30"/> 
void bar(int baz); 

Cho dù điều này có ích cho bạn hay không phụ thuộc vào chính xác bạn làm gì với tệp XML mà trình biên dịch nhổ ra. Thật không may, những thứ như Intellisense (mã hoàn thành và trong IDE tooltips, vv). sẽ không làm bất cứ điều gì với nó.

EDIT: Dùng thử <include>, như được mô tả trong http://msdn.microsoft.com/en-us/library/9h8dy30z.aspx. Đó là một chút nặng, bởi vì nó đòi hỏi một tập tin riêng biệt, nhưng nếu tài liệu của bạn là rất lớn nó có thể được giá trị nó.

Answer 2

Không có chức năng nào như vậy trong các thẻ nhận xét XML chuẩn. Sandcastle Help File Builder mặt khác thực hiện <inheritdoc/> đó là những gì bạn đang tìm kiếm.

Answer 3

Nếu bạn có một giao diện bạn có thể tham khảo một trong những phương pháp từ các phương pháp khác, như thế này:

interface ISomeInterface 
{ 
    /// <summary>Handles this and that.</summary> 
    void SomeMethod(); 

    /// <summary><see cref="ISomeInterface.SomeMethod()"/></summary> 
    /// <param name="i">Param blabla.</param> 
    void SomeMethod(int i); 
} 

class SomeClass : ISomeInterface 
{ 
    /// <summary><see cref="ISomeInterface.SomeMethod()"/></summary> 
    public void SomeMethod() { } 

    /// <summary><see cref="ISomeInterface.SomeMethod(int)"/></summary> 
    public void SomeMethod(int i) { } 
} 

Answer 4

Hãy gọi cho tôi ngớ ngẩn, nhưng việc tìm kiếm tài liệu đặt phạm vi và thay thế cho Go and do something cùng với việc sử dụng lương tâm của Alt + R hoặc Alt + A có thể làm cho điểm này là điểm tranh luận. Một chỉnh sửa - tốt, được nhập ít nhất một lần.

@ Câu trả lời của Reinderien là thông tin ... nhưng không hữu ích khi tận dụng IntelliSense hoặc công cụ xử lý chuẩn là mục tiêu.

@Peter Câu trả lời của Lillevold là thông tin quá và mát mẻ hơn tôi nghĩ ở chỗ nó nói với SHFB để xử lý ... nhưng vẫn không có IntelliSense.

@Paw Câu trả lời của Baltzersen có thể được sử dụng bất kể việc sử dụng giao diện và hấp dẫn ... nhưng cũng không nhận được quyền IntelliSense.

Tôi thích tránh tìm kiếm và thay thế nếu có thể, nhưng nhận được IntelliSense ngay tại đây nói chung sẽ là mối quan tâm đầu tiên của tôi.