2011-12-01 1 views
12

Non so se sto chiamando bene, ma volevo iniziare ad aggiungere della documentazione alle mie classi, metodi, proprietà, ecc. I sa questo è probabilmente super ovvio ma non l'ho mai veramente imparato. Non sono sicuro da dove cominciare.Come aggiungere documentazione tooltip a classi, metodi, proprietà, ecc. In C#?

Giusto per chiarire ogni volta che si passa sopra una classe (o un metodo, una proprietà, ecc.) Mostra un suggerimento in Visual Studio con qualche documentazione su quel metodo specifico.

classe Microsoft.Phone.BackgroundAudio.BackgroundAudioPlayer
Consente di accedere alle funzionalità di sfondo la riproduzione audio, come play, pausa, fast-forward e riavvolgere.

Come si chiama e come posso implementarlo nella mia applicazione C#?

risposta

26

È possibile utilizzare /// o GhostDoc

Edit:

Nel primo caso si otterrà

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

Al secondo

/// <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) { } 
} 
+0

+1 per GhostDoc –

+0

@Shymep GhostDoc sembra fantastico. Dovrò provarlo di sicuro. – loyalpenguin

6

Appena sopra la classe, metodo o proprietà, digitare /// quindi premere Invio. Questo genererà il modello di documentazione per te.

Hai dimenticato di rispondere all'altra parte della tua domanda: questo è noto come XML Documentation Comments e c'è una notevole quantità di informazioni su questo in MSDN.

+0

Basta ricordare che non aggiorna automaticamente i commenti che se si cambia il metodo/classe/proprietà/etc. I documenti API sono sicuramente utili, ma si capisce che crea un altro passaggio manuale quando si apportano modifiche. – David

+0

@competent_tech Sapevo che doveva essere qualcosa di semplice. Non ho mai saputo cosa fosse per haha. Grazie molto. – loyalpenguin

3

Cosa si fa riferimento si chiama documentazione XML o XML-doc.

XML-doc viene eseguito su una classe, un campo, una proprietà, un evento o un metodo utilizzando tre barre in avanti (///), seguite da meta-informazioni in formato XML sulla classe o il suo membro.

VS ti aiuterà a generare e formattare questi commenti con il supporto IntelliSense integrato per i commenti XML, ma c'è uno strumento gratuito chiamato GhostDoc che genererà automaticamente il modello XML-doc completo, ed è anche abbastanza "intelligente" in alcuni casi per cercare di indovinare una descrizione di base per vari elementi della documentazione.

Ecco un esempio di base di documentazione 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; 
}