Herencia de comentarios para C # (en realidad, cualquier idioma)

Supongamos que tengo esta interfaz

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

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

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

Y esta clase

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

¿Hay alguna manera o hay una herramienta que me permita poner automáticamente los comentarios de cada miembro en una clase o interfaz base?

¡Porque odio volver a escribir los mismos comentarios para cada subclase derivada!

GhostDoc hace exactamente eso. Para los métodos que no se heredan, intenta crear una descripción a partir del nombre.

FlingThing() se convierte en "Flings the Thing"

Siempre puedes usar la <inheritdoc />etiqueta.

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

Úselo /// <inheritdoc/>si desea herencia. Evite GhostDoc o cualquier cosa por el estilo.

Estoy de acuerdo en que es molesto que los comentarios no se hereden. Sería un complemento bastante simple de crear si alguien tuviera tiempo (desearía tenerlo).

Dicho esto, en nuestra base de código colocamos comentarios XML solo en las interfaces y agregamos comentarios de implementación adicionales a la clase. Esto funciona para nosotros ya que nuestras clases son privadas / internas y solo la interfaz es pública. Cada vez que usamos los objetos a través de las interfaces, los comentarios completos se muestran en intellisence.

GhostDoc es un buen comienzo y ha facilitado el proceso de escribir comentarios. Es especialmente útil mantener los comentarios actualizados cuando agrega / elimina parámetros, vuelve a ejecutar GhostDoc y actualizará la descripción.

Java tiene esto y lo uso todo el tiempo. Solo haz:

/**
 * {@inheritDoc}
 */

Y la herramienta Javadoc lo resuelve.

C # tiene un marcador similar:

<inheritDoc/>

Puede leer más aquí:

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

Yo diría que use directamente el

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

Y

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

Tienes que poner estos comentarios solo en la línea anterior de tu clase / método

Esto obtendrá la información de sus comentarios, por ejemplo, de una interfaz que haya documentado como:

    /// <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 tiene una opción para copiar los comentarios de la clase base o interfaz.

Otra forma es utilizar la <see />etiqueta de documentación XML. Este es un esfuerzo adicional, pero funciona fuera de la caja ...

Aquí hay unos ejemplos:

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

Actualizar:

Ahora prefiero usar lo /// <inheritdoc/>que ahora es compatible con ReSharper.

Terminé creando una herramienta para posprocesar los archivos de documentación XML para agregar soporte para reemplazar la <inheritdoc/>etiqueta en los archivos de documentación XML. Disponible en www.inheritdoc.io (versión gratuita disponible).

Bueno, hay una especie de solución nativa que encontré para .NET Core 2.2

La idea es usar <include>etiqueta.

Puedes agregar <GenerateDocumentationFile>true</GenerateDocumentationFile>tu.csproj archivo.

Es posible que tenga una interfaz:

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

Y algo que hereda de ella:

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, da un poco de miedo, pero agrega los elementos esperados al YourNamespace.xml.

Si se construye Debugconfiguración, se puede intercambiar Releasepara Debugel fileatributo de la includeetiqueta.

Para encontrar una referencia correcta member, namesimplemente abra el Documentation.xmlarchivo generado .

También asumo que este enfoque requiere que un proyecto o solución se compile al menos dos veces (la primera vez para crear un archivo XML inicial y la segunda para copiar elementos de él a sí mismo).

El lado positivo es que Visual Studio valida los elementos copiados, por lo que es mucho más fácil mantener la documentación y el código sincronizados con la interfaz / clase base, etc. (por ejemplo, nombres de argumentos, nombres de parámetros de tipo, etc.).

En mi proyecto, terminé con ambos <inheritdoc/>(para DocFX) y <include/>(Para publicar paquetes NuGet y para validación en 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();