Nhận xét Kế thừa cho C # (thực tế là bất kỳ ngôn ngữ nào)

Giả sử tôi có giao diện này

public interface IFoo
{
    ///<summary>
    /// Foo method
    ///</summary>
    void Foo();

    ///<summary>
    /// Bar method
    ///</summary>
    void Bar();

    ///<summary>
    /// Situation normal
    ///</summary>
    void Snafu();
}

Và lớp học này

public class Foo : IFoo
{
    public void Foo() { ... }
    public void Bar() { ... }
    public void Snafu() { ... }
}

Có cách nào hoặc có công cụ nào có thể cho phép tôi tự động đưa vào nhận xét của từng thành viên trong lớp cơ sở hoặc giao diện không?

Bởi vì tôi ghét viết lại các nhận xét giống nhau cho mỗi lớp con dẫn xuất!

GhostDoc thực hiện chính xác điều đó. Đối với các phương thức không được kế thừa, nó cố gắng tạo mô tả ngoài tên.

FlingThing() trở thành "Flings the Thing"

Bạn luôn có thể sử dụng <inheritdoc />thẻ.

public class Foo : IFoo
{
    /// <inheritdoc />
    public void Foo() { ... }
    /// <inheritdoc />
    public void Bar() { ... }
    /// <inheritdoc />
    public void Snafu() { ... }
}

Sử dụng /// <inheritdoc/> nếu bạn muốn kế thừa. Tránh GhostDoc hoặc bất cứ thứ gì tương tự.

Tôi đồng ý rằng thật khó chịu khi nhận xét không được kế thừa. Nó sẽ là một bổ trợ khá đơn giản để tạo nếu ai đó có thời gian (tôi ước tôi đã làm như vậy).

Điều đó nói rằng, trong cơ sở mã của chúng tôi, chúng tôi chỉ đặt các nhận xét XML trên các giao diện và thêm các nhận xét triển khai bổ sung vào lớp. Điều này phù hợp với chúng tôi vì các lớp của chúng tôi là riêng tư / nội bộ và chỉ giao diện là công khai. Bất cứ khi nào chúng tôi sử dụng các đối tượng thông qua các giao diện, chúng tôi có đầy đủ các nhận xét hiển thị trong nội dung.

GhostDoc là một khởi đầu tốt và đã giúp quá trình viết nhận xét dễ dàng hơn. Điều đặc biệt hữu ích là giữ cho các nhận xét được cập nhật khi bạn thêm / xóa các tham số, chạy lại GhostDoc và nó sẽ cập nhật mô tả.

Java có cái này, và tôi sử dụng nó mọi lúc. Cứ làm đi:

/**
 * {@inheritDoc}
 */

Và công cụ Javadoc đã tìm ra điều đó.

C # có điểm đánh dấu tương tự:

<inheritDoc/>

Bạn có thể đọc thêm ở đây:

http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-e50c66a0221d.htm

Tôi muốn nói là sử dụng trực tiếp

/// <inheritdoc cref="YourClass.YourMethod"/>  --> For methods inheritance

Và

/// <inheritdoc cref="YourClass"/>  --> For directly class inheritance

Bạn phải đặt nhận xét này ngay trên dòng trước của lớp / phương thức của bạn

Thao tác này sẽ lấy thông tin về nhận xét của bạn, ví dụ từ giao diện mà bạn đã ghi lại như:

    /// <summary>
    /// This method is awesome!
    /// </summary>
    /// <param name="awesomeParam">The awesome parameter of the month!.</param>
    /// <returns>A <see cref="AwesomeObject"/> that is also awesome...</returns>
    AwesomeObject CreateAwesome(WhateverObject awesomeParam);

Resharper có một tùy chọn để sao chép các nhận xét từ lớp cơ sở hoặc giao diện.

Một cách khác là sử dụng <see />thẻ tài liệu XML. Đây là một số nỗ lực bổ sung nhưng hoạt động hiệu quả ...

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

/// <summary>
/// Implementation of <see cref="IFoo"/>.
/// </summary>
public class Foo : IFoo
{
    /// <summary>
    /// See <see cref="IFoo"/>.
    /// </summary>
    public void Foo() { ... }

    /// <summary>
    /// See <see cref="IFoo.Bar"/>
    /// </summary>
    public void Bar() { ... }

    /// <summary>
    /// This implementation of <see cref="IFoo.Snafu"/> uses the a caching algorithm for performance optimization.
    /// </summary>
    public void Snafu() { ... }
}

Cập nhật:

Bây giờ tôi thích sử dụng /// <inheritdoc/>mà hiện đã được hỗ trợ bởi ReSharper.

Tôi đã kết thúc việc tạo một công cụ để xử lý hậu các tệp tài liệu XML để thêm hỗ trợ cho việc thay thế <inheritdoc/>thẻ trong chính các tệp tài liệu XML. Có tại www.inheritdoc.io (có phiên bản miễn phí).

Vâng, có một loại giải pháp gốc, tôi đã tìm thấy cho .NET Core 2.2

Ý tưởng là sử dụng <include> thẻ.

Bạn có thể thêm <GenerateDocumentationFile>true</GenerateDocumentationFile>bạn.csproj một tập tin.

Bạn có thể có một giao diện:

namespace YourNamespace
{
    /// <summary>
    /// Represents interface for a type.
    /// </summary>
    public interface IType
    {
        /// <summary>
        /// Executes an action in read access mode.
        /// </summary>
        void ExecuteAction();
    }
}

Và một cái gì đó kế thừa từ nó:

using System;

namespace YourNamespace
{
    /// <summary>
    /// A type inherited from <see cref="IType"/> interface.
    /// </summary>
    public class InheritedType : IType
    {
        /// <include file='bin\Release\netstandard2.0\YourNamespace.xml' path='doc/members/member[@name="M:YourNamespace.IType.ExecuteAction()"]/*'/>
        public void ExecuteAction() => Console.WriteLine("Action is executed.");
    }
}

Ok, nó có một chút đáng sợ, nhưng nó thêm các yếu tố được mong đợi vào YourNamespace.xml.

Nếu bạn xây dựng Debugcấu hình, bạn có thể trao đổi Releasecho Debugtrong filethuộc tính của includethẻ.

Để tìm một đúng memberlà nameđể tham khảo được tạo ra chỉ cần mở Documentation.xmltập tin.

Tôi cũng giả định rằng cách tiếp cận này yêu cầu một dự án hoặc giải pháp phải được xây dựng ít nhất hai lần (lần đầu tiên để tạo tệp XML ban đầu và lần thứ hai để sao chép các phần tử từ nó sang chính nó).

Mặt sáng sủa là Visual Studio xác thực các phần tử được sao chép, vì vậy việc giữ cho tài liệu và mã đồng bộ với giao diện / lớp cơ sở, v.v. sẽ dễ dàng hơn nhiều (ví dụ: tên của đối số, tên của tham số kiểu, v.v.).

Tại dự án của mình, tôi đã kết thúc với cả <inheritdoc/>(cho DocFX) và <include/>(Để xuất bản các gói NuGet và để xác thực tại Visual Studio):

        /// <inheritdoc />
        /// <include file='bin\Release\netstandard2.0\Platform.Threading.xml' path='doc/members/member[@name="M:Platform.Threading.Synchronization.ISynchronization.ExecuteReadOperation(System.Action)"]/*'/>
        public void ExecuteReadOperation(Action action) => action();