Các cách để đồng bộ hóa nhận xét giao diện và triển khai trong C#

Question

Có cách tự động để đồng bộ hóa nhận xét giữa giao diện và cách triển khai giao diện không? Tôi hiện đang làm tài liệu cho cả hai và không muốn giữ chúng theo cách thủ công.

UPDATE:

xem xét mã này:

interface IFoo{ 
    /// <summary> 
    /// Commenting DoThis method 
    /// </summary> 
    void DoThis(); 
} 
class Foo : IFoo { 
    public void DoThis(); 
} 

Khi tôi tạo ra lớp như thế này:

IFoo foo=new Foo(); 
foo.DoThis();//comments are shown in intellisense 

đây bình luận không được hiển thị:

Foo foo=new Foo(); 
foo.DoThis();//comments are not shown in intellisense 

CácThẻsẽ tạo ra tài liệu hoàn hảo trong Sand Castle, nhưng nó không hoạt động trong các chú giải công cụ intelliSense.

Hãy chia sẻ ý tưởng của bạn.

Cảm ơn.

Answer 1

Bạn có thể thực hiện việc này khá dễ dàng bằng cách sử dụng thẻ Microsoft Sandcastle (hoặc NDoc) inheritdoc. Nó không được chính thức hỗ trợ bởi đặc điểm kỹ thuật, nhưng các thẻ tùy chỉnh hoàn toàn có thể chấp nhận được, và thực sự Microsoft đã chọn sao chép (và một hoặc hai thẻ khác) từ NDoc khi họ tạo Sandcastle.

/// <inheritdoc/> 
/// <remarks> 
/// You can still specify all the normal XML tags here, and they will 
/// overwrite inherited ones accordingly. 
/// </remarks> 
public void MethodImplementingInterfaceMethod(string foo, int bar) 
{ 
    // 
} 

Here là trang trợ giúp từ GUI trình xây dựng tệp trợ giúp Sandcastle, mô tả cách sử dụng đầy đủ.

(Tất nhiên, đây không phải là đặc biệt "đồng bộ hóa", như câu hỏi của bạn đề cập đến, nhưng nó dường như là chính xác những gì bạn đang tìm kiếm dù sao.)

Là một lưu ý, điều này có vẻ giống như một ý tưởng hoàn toàn công bằng với tôi, mặc dù tôi đã quan sát thấy rằng một số người nghĩ rằng bạn nên luôn luôn tôn trọng ý kiến ​​trong các lớp học có nguồn gốc và thực hiện. (Tôi đã thực sự tự mình làm tài liệu cho một trong các thư viện của mình và tôi không thấy bất kỳ vấn đề gì.) Hầu như không có lý do gì để các ý kiến ​​khác nhau cả, vậy tại sao không chỉ thừa kế và làm điều đó một cách dễ dàng?

Chỉnh sửa: Về cập nhật của bạn, Sandcastle cũng có thể xử lý điều đó cho bạn. Sandcastle có thể xuất ra phiên bản sửa đổi của tệp XML thực tế mà nó sử dụng cho đầu vào, có nghĩa là bạn có thể phân phối phiên bản sửa đổi này cùng với thư viện DLL của bạn thay vì được tạo trực tiếp bởi Visual Studio, có nghĩa là bạn có các nhận xét trong intellisense cũng như các tập tin tài liệu (CHM, bất cứ điều gì).

Answer 2

Đừng làm điều đó. Hãy suy nghĩ về nó theo cách này - nếu cả hai ý kiến ​​được yêu cầu phải giống nhau mọi lúc, thì một trong số chúng không cần thiết. Có phải là một lý do cho bình luận (bên cạnh một số nghĩa vụ kỳ lạ để bình luận-chặn tất cả các chức năng và biến), do đó bạn cần phải tìm ra lý do duy nhất là gì và tài liệu đó.

Answer 3

Tôi thường viết nhận xét như thế này:

/// <summary> 
/// Implements <see cref="IMyInterface.Foo(string, int)"/> 
/// </summary> 
/// <returns></returns> 

Các phương pháp được sử dụng chỉ bởi giao diện, do đó, nhận xét này thậm chí không được thể hiện trong tooltips khi mã hóa.

Edit:

Nếu bạn muốn xem tài liệu khi bạn gọi lớp trực tiếp và không sử dụng giao diện, bạn cần phải viết nó hai lần hoặc sử dụng một công cụ như GhostDoc.

Answer 4

Hãy thử GhostDoc! Nó làm việc cho tôi :-)

Edit: Bây giờ tôi đã được thực hiện nhận thức hỗ trợ Sandcastle cho <inheritdoc/>, tôi tán thành bài Noldorin của. Đó là một giải pháp tốt hơn nhiều. Tuy nhiên, tôi vẫn khuyên bạn nên sử dụng GhostDoc.

Answer 5

Nếu bạn hiện chưa sử dụng, tôi khuyên bạn nên sử dụng addon Visual Studio miễn phí được gọi là GhostDoc. Nó giúp giảm bớt quá trình tài liệu. Hãy xem my comment về một câu hỏi có liên quan.

Mặc dù GhostDoc sẽ không làm cho đồng bộ hóa tự động, nó có thể giúp bạn với các tình huống sau:

Bạn có một phương pháp giao diện tài liệu. Thực hiện giao diện này trong một lớp, nhấn phím tắt GhostDoc, Ctrl-Shift-D và nhận xét XML từ giao diện sẽ được thêm vào phương thức được triển khai.

Chuyển đến tùy chọn Tùy chọn -> Bàn phím và gán khóa cho GhostDoc.AddIn.RebuildDocumentation (Tôi đã sử dụng Ctrl-Shift-Alt-D). alt text http://i44.tinypic.com/10dd1f9.png

Bây giờ, nếu bạn thay đổi những nhận xét XML trên giao diện , chỉ cần nhấn phím tắt này vào phương pháp thực hiện, và các tài liệu sẽ được cập nhật. Thật không may, điều này không làm việc ngược lại.

Answer 6

/// <inheritDoc/> 

Read here

Use this

Answer 7

Với ReSharper bạn có thể sao chép nó, nhưng tôi không nghĩ rằng nó là đồng bộ tất cả các thời gian.

Answer 8

Tôi có câu trả lời hay hơn: FiXml.

Nhân bản cách tiếp cận được chắc chắn 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 - thường nó không sửa đổi .xml các tệp có chứa các nhận xét XML được trích xuất (cuối cùng, điều này không thể được thực hiện "khi đang di chuyển" trong quá trình biên dịch).
• 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ó đề cập đến vài trường hợp gây phiền nhiễu liên quan đến văn bản tài liệu XML trong các thứ tiếng:

• Không hỗ trợ kế thừa những 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.

Answer 9

Tôi đã xây dựng một thư viện để xử lý sau các tệp tài liệu XML để thêm hỗ trợ cho thẻ < inheritdoc/>.

Mặc dù nó không hỗ trợ Intellisense trong mã nguồn, nó cho phép các tệp tài liệu XML được sửa đổi được bao gồm trong gói NuGet và do đó làm việc với Intellisense trong các gói NuGet được tham chiếu.

Thông tin thêm tại www.inheritdoc.io (phiên bản miễn phí có sẵn).