¿Cómo agregar la información sobre herramientas de la documentación a clases, métodos, propiedades, etc. en C#?

Question

No estoy seguro de si estoy llamando a esto, pero quería comenzar a agregar documentación a mis clases, métodos, propiedades, etc. I saber esto es probablemente muy obvio, pero nunca lo aprendí. No estoy seguro de por dónde empezar.

Solo para aclarar cada vez que pase sobre una clase (o método, propiedad, etc.) muestra una información sobre herramientas en Visual Studio con cierta documentación sobre ese método específico.

Microsoft.Phone.BackgroundAudio.BackgroundAudioPlayer clase
Proporciona acceso a fondo la función de reproducción de audio, tales como reproducción, pausa, avance rápido, y rebobinado.

¿Cómo se llama y cómo puedo implementar esto en mi aplicación C#?

Answer 1

Puede utilizar /// o GhostDoc

Editar:

En primer caso obtendrá

/// <summary> 
/// 
/// </summary> 
class A 
{ 
    /// <summary> 
    /// 
    /// </summary> 
    public A() { } 

    /// <summary> 
    /// 
    /// </summary> 
    public int Property { get; set; } 

    /// <summary> 
    /// 
    /// </summary> 
    /// <param name="obj"></param> 
    public void Method(object obj) { } 
} 

En segundo

/// <summary> 
/// 
/// </summary> 
class B 
{ 

    /// <summary> 
    /// Initializes a new instance of the <see cref="B"/> class. 
    /// </summary> 
    public B() { } 

    /// <summary> 
    /// Gets or sets the property. 
    /// </summary> 
    /// <value> 
    /// The property. 
    /// </value> 
    public int Property { get; set; } 

    /// <summary> 
    /// Methods the specified obj. 
    /// </summary> 
    /// <param name="obj">The obj.</param> 
    public void Method(object obj) { } 
} 

Answer 2

Justo encima de su clase, método o propiedad, escriba /// y luego presione regresar. Esto generará la plantilla de documentación para usted.

Se olvidó de responder la otra parte de su pregunta: esto se conoce como XML Documentation Comments y hay una gran cantidad de información al respecto en MSDN.

Answer 3

Lo que se está haciendo referencia a se llama documentación XML o XML-doc.

XML-doc se realiza en una clase, campo, propiedad, evento o método utilizando tres barras diagonales (///), seguidas de metainformación con formato XML sobre la clase o su miembro.

VS le ayudará a generar y formatear estos comentarios con soporte IntelliSense incorporado para comentarios XML, pero hay una herramienta gratuita llamada GhostDoc que generará automáticamente la plantilla XML-doc completa, e incluso es lo suficientemente "inteligente" en algunos casos para tratar de adivinar una descripción básica de varios elementos de la documentación.

Aquí hay un ejemplo básico de la documentación XML:

/// <summary> 
/// Defines the behavior of a class following the Repository pattern for data access 
/// with basic atomic operation control. 
/// </summary> 
/// <typeparam name="TRest">An interface derived from IDomainObject that describes domain objects 
/// that can be retrieved or saved by this Repository.</typeparam> 
public interface IRepository<TRest> : IDisposable where TRest : IDomainObject 
{ 
    /// <summary> 
    /// Begins a new unit of work to be performed atomically by the Repository. 
    /// </summary> 
    /// <returns>A token class representing the unit of work.</returns> 
    IUnitOfWork BeginUnitOfWork(); 

    /// <summary> 
    /// Commits all work performed under the specified unit of work. 
    /// </summary> 
    /// <param name="unitOfWork">The unit of work.</param> 
    void CommitUnitOfWork(IUnitOfWork unitOfWork); 

    /// <summary> 
    /// Rolls back the specified unit of work. 
    /// </summary> 
    /// <param name="unitOfWork">The unit of work.</param> 
    void RollBackUnitOfWork(IUnitOfWork unitOfWork); 

    /// <summary> 
    /// Saves the specified domain object to the data source controlled by the repository. 
    /// </summary> 
    /// <typeparam name="T"></typeparam> 
    /// <param name="domainObject">The domain object.</param> 
    /// <param name="unitOfWork">The unit of work.</param> 
    void Save<T>(T domainObject, IUnitOfWork unitOfWork) where T : class, TRest; 

    /// <summary> 
    /// Begins a Linq query for a specific object type, to be performed against the Repository's data source. 
    /// </summary> 
    /// <typeparam name="T"></typeparam> 
    /// <param name="unitOfWork">The unit of work.</param> 
    /// <returns>An IQueryable representing the query to be performed.</returns> 
    IQueryable<T> QueryFor<T>(IUnitOfWork unitOfWork) where T : class, TRest; 

    /// <summary> 
    /// Performs the specified Action using a new unit of work, with commits and rollbacks as necessary. 
    /// </summary> 
    /// <typeparam name="T"></typeparam> 
    /// <param name="func">The Action to perform. The lambda or named method must accept an IUnitOfWork as a parameter.</param> 
    /// <param name="commit">if set to <c>true</c>, commit the unit of work.</param> 
    void PerformInNewUnitOfWork<T>(Action<IUnitOfWork> func, bool commit = false); 

    /// <summary> 
    /// Performs the specified Func using a new unit of work, with commits and rollbacks as necessary. 
    /// </summary> 
    /// <typeparam name="T"></typeparam> 
    /// <param name="func">The function to evaluate. The lambda or named method must accept an IUnitOfWork as a parameter.</param> 
    /// <returns>A single object of the generic type, returned by the function.</returns> 
    /// <param name="commit">if set to <c>true</c>, commit the unit of work.</param> 
    T PerformInNewUnitOfWork<T>(Func<IUnitOfWork, T> func, bool commit = false) where T : class, TRest; 

    /// <summary> 
    /// Performs the specified Func using a new unit of work, with commits and rollbacks as necessary. 
    /// </summary> 
    /// <typeparam name="T"></typeparam> 
    /// <param name="func">The Function to evaluate. The lambda or named method must accept an IUnitOfWork as a parameter.</param> 
    /// <returns>An enumerable set of objects of the generic type, returned by the function.</returns> 
    /// <param name="commit">if set to <c>true</c>, commit the unit of work.</param> 
    IEnumerable<T> PerformInNewUnitOfWork<T>(Func<IUnitOfWork, IEnumerable<T>> func, bool commit = false) where T : class, TRest; 

    /// <summary> 
    /// Attaches the specified domain object to the current Unit of Work, allowing operations to be performed on it. 
    /// </summary> 
    /// <typeparam name="T"></typeparam> 
    /// <param name="domainObject">The domain object.</param> 
    /// <param name="unitOfWork">The unit of work.</param> 
    void Attach<T>(T domainObject, IUnitOfWork unitOfWork) where T : class, TRest; 

    /// <summary> 
    /// Detaches the specified domain object to the current Unit of Work. 
    /// </summary> 
    /// <typeparam name="T"></typeparam> 
    /// <param name="domainObject">The domain object.</param> 
    /// <param name="unitOfWork">The unit of work.</param> 
    void Detach<T>(T domainObject, IUnitOfWork unitOfWork) where T : class, TRest; 

    /// <summary> 
    /// Refreshes the specified collection of persistent elements with the most recent persisted data. 
    /// </summary> 
    /// <typeparam name="T"></typeparam> 
    /// <param name="elements">The list of elements to refresh.</param> 
    /// <param name="unitOfWork">The Unit of Work under which to perform the operation.</param> 
    void Refresh<T>(IList<T> elements, IUnitOfWork unitOfWork) where T : class, TRest; 

    /// <summary> 
    /// Deletes the specified domain object from the data store. 
    /// Usually performs a physical delete; logical deletes are most often done through updates. 
    /// </summary> 
    /// <typeparam name="T"></typeparam> 
    /// <param name="domainObject">The domain object to delete.</param> 
    /// <param name="unitOfWork">The unit of work under which to perform the operation.</param> 
    void Delete<T>(T domainObject, IUnitOfWork unitOfWork) where T : class, TRest; 
}