How to add documentation tooltip to classes, methods, properties, etc. in C#?

Question

Not sure if I'm even calling this right but I wanted to start adding some documentation to my classes, methods, properties, etc. I know this is probably super obvious but I never really learned it. I'm not sure where to start.

Just to clarify whenever you roll over a class (or method, property, etc.) it shows a tooltip in Visual Studio with some documentation on that specific method.

class Microsoft.Phone.BackgroundAudio.BackgroundAudioPlayer
Provides background access to audio playback functionality such as play, pause, fast-forward, and rewind.

What is that called and how can I implement this in my C# application?

Solution 1

You can use /// or GhostDoc

Edit:

In first case you'll get

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

In second

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

Solution 2

Just above your class, method or property, type /// then press return. This will generate the documentation template for you.

Forgot to answer the other part of your question: this is known as XML Documentation Comments and there is a substantial amount of information about this in MSDN.

Solution 3

What you are referring to is called XML documentation or XML-doc.

XML-doc is performed on a class, field, property, event or method using three forward-slashes (///), followed by XML-formatted meta-information about the class or its member.

VS will help you generate and format these comments with built-in IntelliSense support for XML comments, but there is a free tool called GhostDoc that will automatically generate the full XML-doc template, and it's even "smart" enough in some cases to try to guess a basic description for various elements of the documentation.

Here's a basic example of XML documentation:

/// <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;
}

Comments

[David]

Just remember that it doesn't automatically update the comments if you change the method/class/property/etc. API docs are definitely useful, but understand that it creates another manual step when making changes.

[Edward]

@competent_tech I knew it had to be something simple. I never knew what that was for haha. Many thanks.

[Edward]

@Shymep GhostDoc looks awesome. I will have to try it out for sure.

[Martin KS]

This question is also a top google hit if you're looking for the same information for VB.NET - so it might be useful to future visitors to know that all you need to do is replace /// with ''' to translate between the two - and if you type it by hand visual studio will auto-complete useful fields for you to fill in.