C # için Yorum Devralma (aslında herhangi bir dil)

Bu arayüze sahip olduğumu varsayalım

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

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

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

Ve bu sınıf

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

Bir temel sınıf veya arayüzdeki her üyenin yorumlarını otomatik olarak eklememe izin veren bir yol var mı veya bir araç var mı?

Çünkü türetilmiş her alt sınıf için aynı yorumları yeniden yazmaktan nefret ediyorum!

GhostDoc tam olarak bunu yapar. Miras alınmayan yöntemler için isimden bir açıklama oluşturmaya çalışır.

FlingThing() olur "Flings the Thing"

<inheritdoc />Etiketi her zaman kullanabilirsiniz :

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

crefÖzniteliği kullanarak, tamamen farklı bir sınıf veya ad alanındaki tamamen farklı bir üyeye bile başvurabilirsiniz!

public class Foo
{
    /// <inheritdoc cref="System.String.IndexOf" />
    public void Bar() { ... } // this method will now have the documentation of System.String.IndexOf
}

/// <inheritdoc/>Miras istiyorsanız kullanın . GhostDoc veya benzeri şeylerden kaçının.

Yorumların miras alınmamasının can sıkıcı olduğuna katılıyorum. Birinin vakti olsaydı oluşturmak oldukça basit bir eklenti olurdu (keşke yapsaydım).

Bununla birlikte, kod tabanımızda sadece arayüzlere XML yorumları koyarız ve sınıfa ekstra uygulama yorumları ekleriz. Sınıflarımız özel / dahili olduğundan ve yalnızca arayüz herkese açık olduğundan, bu bizim için işe yarar. Nesneleri arayüzler aracılığıyla her kullandığımızda, tam yorumlara sahip oluruz.

GhostDoc iyi bir başlangıçtır ve süreci yorum yazmayı kolaylaştırmıştır. Parametreleri eklediğinizde / kaldırdığınızda, GhostDoc'u yeniden çalıştırdığınızda açıklamaları güncel tutmak özellikle yararlıdır ve açıklamayı güncelleyecektir.

Java'da bu var ve her zaman kullanıyorum. Sadece yap:

/**
 * {@inheritDoc}
 */

Ve Javadoc aracı bunu çözüyor.

C # benzer bir işaretleyiciye sahiptir:

<inheritDoc/>

Daha fazlasını buradan okuyabilirsiniz:

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

Doğrudan kullanmayı söyleyebilirim

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

Ve

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

Bu yorumları sınıfınızın / yönteminizin önceki satırına koymalısınız.

Bu, örneğin aşağıdaki gibi belgelediğiniz bir arayüzden yorumlarınızın bilgilerini alacaktır:

    /// <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, yorumları temel sınıftan veya arayüzden kopyalama seçeneğine sahiptir.

Başka bir yol da <see />XML dokümantasyon etiketini kullanmaktır . Bu biraz fazladan çaba ama kutunun dışında çalışıyor ...

İşte bazı örnekler:

/// <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() { ... }
}

Güncelleme:

Şimdi /// <inheritdoc/>ReSharper tarafından desteklenen kullanmayı tercih ediyorum .

<inheritdoc/>XML dokümantasyon dosyalarının kendisinde etiketi değiştirmek için destek eklemek üzere XML dokümantasyon dosyalarını sonradan işlemek için bir araç oluşturdum . Www.inheritdoc.io adresinde mevcuttur (ücretsiz sürümü mevcuttur).

Bir tür yerel çözüm var, .NET Core 2.2 için buldum

Fikir <include>etiketi kullanmaktır .

Ekleyebilir <GenerateDocumentationFile>true</GenerateDocumentationFile>senin .csprojbir dosya.

Bir arayüzünüz olabilir:

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

Ve ondan miras kalan bir şey:

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.");
    }
}

Tamam, biraz korkutucu, ancak beklenen öğeleri YourNamespace.xml.

Eğer inşa edersen Debug yapılandırmayı, sen takas olabilir Releaseiçin Debugde fileoznıtelığıinclude etiketi.

Doğru bulmak için membernameReferans verecek 'ları sadece oluşturulan Documentation.xmldosyayı açın .

Ayrıca, bu yaklaşımın bir proje veya çözümün en az iki kez oluşturulmasını gerektirdiğini varsayıyorum (ilk kez bir ilk XML dosyası oluşturmak ve ikinci kez öğeleri ondan kendisine kopyalamak için).

İşin iyi tarafı, Visual Studio'nun kopyalanan öğeleri doğrulamasıdır, bu nedenle belgeleri ve kodu arabirim / temel sınıf vb. (Örneğin bağımsız değişkenlerin adları, tür parametrelerinin adları, vb.) İle senkronize tutmak çok daha kolaydır.

<inheritdoc/>Projemde , hem (DocFX için) hem de (NuGet <include/>paketlerini yayınlamak ve Visual Studio'da doğrulama için):

        /// <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();