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

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

CẬP NHẬT:

Hãy 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 lớp như thế này:

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

Ở đây nhận xét không được hiển thị:

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

Các <inheritDoc/>thẻ sẽ hoàn toàn tạo ra các tài liệu trong Sand Castle, nhưng nó không hoạt động trong tooltips IntelliSense.

Hãy chia sẻ ý kiến ​​của bạn.

Cảm ơn.

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 thông số kỹ thuật chính thức hỗ trợ, nhưng các thẻ tùy chỉnh hoàn toàn có thể chấp nhận được và thực sự là Microsoft đã chọn sao chép thẻ này (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)
{
    //
}

Đây là trang trợ giúp từ GUI của Trình tạo tệp trợ giúp lâu đài cát, mô tả đầy đủ cách sử dụng của nó.

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

Lưu ý, điều này nghe có vẻ như là một ý tưởng hoàn toàn công bằng đối 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 tôn trọng các nhận xét trong các lớp dẫn xuất và được triển khai. (Tôi thực sự đã tự làm việc đó trong việc ghi lại một trong các thư viện của mình và tôi không gặp bất kỳ vấn đề gì.) Hầu như luôn luôn không có lý do gì để các nhận xét khác nhau cả, vậy tại sao không kế thừa và thực hiện nó một cách dễ dàng?

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

Nếu bạn chưa sử dụng nó, tôi thực sự khuyên bạn nên bổ sung Visual Studio miễn phí có tên là GhostDoc . Nó giúp giảm bớt quy trình tài liệu. Hãy xem bình luận của tôi về một câu hỏi có liên quan.

Mặc dù GhostDoc sẽ không tự động đồng bộ hóa nhưng nó có thể giúp bạn trong trường hợp sau:

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

Đi tới Tùy chọn -> Cài đặt bàn phím và gán một phím cho GhostDoc.AddIn.RebuildDocumentation(Tôi đã sử dụng Ctrl-Shift-Alt-D).

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

Tôi thường viết những bình luận như thế này:

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

Các phương pháp chỉ được sử dụng bởi giao diện, vì vậy nhận xét này thậm chí không được hiển thị trong chú giải công cụ khi viết mã.

Biên tập:

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 viết nó hai lần hoặc sử dụng một công cụ như GhostDoc.

Hãy thử GhostDoc ! Nó hoạt động cho tôi :-)

Chỉnh sửa: Bây giờ tôi đã biết về sự ủng hộ của Sandcastle <inheritdoc/>, tôi tán thành bài đăng của Noldorin. Đó là một giải pháp tốt hơn nhiều. Tuy nhiên, tôi vẫn đề xuất GhostDoc trên cơ sở chung.

Tôi có một câu trả lời hay hơn: FiXml . , Tôi là một trong những tác giả của nó

Sao chép cách tiếp cận chắc chắn là hiệu quả, nhưng nó có những nhược điểm đáng kể, ví dụ:

• Khi nhận xét ban đầu bị thay đổi (thường xuyên xảy ra trong quá trình phát triển), bản sao của nó sẽ không bị thay đổi.
• Bạn đang tạo ra một lượng lớn các bản sao. 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ụ: Duplicate Finder trong Team City), nó sẽ chủ yếu tìm thấy nhận xét của bạn.

Như đã đề cập, có <inheritdoc>thẻ trong Sandcastle , nhưng nó có một số nhược điểm so với FiXml:

• Sandcastle tạo ra các tệp trợ giúp HTML đã biên dịch - thông thường nó không sửa đổi .xmlcá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 "nhanh chóng" trong quá trình biên dịch).
• Quá trình triển khai của Sandcastle kém hiệu quả hơn. Ví dụ: là không <see ... copy="true" />.

Xem mô tả của Sandcastle<inheritdoc> để biết thêm chi tiết.

Mô tả ngắn gọn về FiXml: nó là bộ xử lý hậu kỳ của tài liệu XML do C # \ Visual Basic .Net tạo ra. Nó được thực hiện dưới dạng nhiệm vụ MSBuild, vì vậy 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 số 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. Tức là một tài liệu cho bất kỳ thành viên bị ghi đè nào nên được viết từ đầu, mặc dù thông thường bạn khá muốn kế thừa í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ư “Loại này là singleton - sử dụng thuộc tính của nó <see cref="Instance" />để lấy phiên bản duy nhất của nó.”, Hoặc thậm chí “Khởi tạo phiên bản mới của <CurrentType>lớp”.

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

• <inheritdoc />, <inherited /> thẻ
• <see cref="..." copy="..." />thuộc tính trong <see/>thẻ.

Đây là trang web của nó và trang tải xuống .

/// <inheritDoc/>

Đọc ở đây

Dùng cái này

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

Mặc dù nó không hữu ích với Intellisense trong mã nguồn, nhưng nó cho phép các tệp tài liệu XML đã sửa đổi được đưa vào gói NuGet và do đó hoạt động với Intellisense trong các gói NuGet được tham chiếu.

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

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

Với ReSharper, bạn có thể sao chép nó, nhưng tôi không nghĩ rằng nó luôn đồng bộ.