CODEWITHSUNDEEP
c#visual-studio
SimonG
SimonG

Reputation: 322

Add usage information for a function in its Visual Studio tooltip

I'm trying to add information on how to use my function in the Visual Studio tooltip, similar to how it is done by default with every async function.

Example:

/// <summary>
/// Executes an asynchron operation
/// </summary>
/// <usage> <-- I am looking for something like this
/// try
/// {
///     bool x = await DoSomething();
/// }
/// finally
/// {
///    await CleanUp();
/// }
/// </usage>
public async Task<bool> DoSomething()
{
    return await SomeAsynchronOperation();
}

I tried using the <example> tag, but this text is not shown in the tooltip.

There is no description of any other tag in the official documentation that allows something like that.

How is it done with the async functions and is there a possibility to do the same thing for other functions?

Upvotes: 2

Views: 669

Answers (1)

Anton Sizikov
Anton Sizikov

Reputation: 9230

That seems to me like a special VisualStudio feature for Task based methods only.

The Task reference code doesn't show anything special in XML comment related to the way you should call it:

        /// <summary>
        /// Queues the specified work to run on the ThreadPool and returns a proxy for the
        /// Task returned by <paramref name="function"/>.
        /// </summary>
        /// <param name="function">The work to execute asynchronously</param>
        /// <returns>A Task that represents a proxy for the Task returned by <paramref name="function"/>.</returns>
        /// <exception cref="T:System.ArgumentNullException">
        /// The <paramref name="function"/> parameter was null.
        /// </exception>
        public static Task Run(Func<Task> function)
        {
            return Run(function, default(CancellationToken));
        }

I guess the only thing you can do is to use a combination of <example> and <code> tags.

 ///<summary>Credit account with amount passed as parameter</summary>
 ///<example>After class initialisation, call this method:
 ///<code>
 ///var account = new Account(10, 2000);
 ///account.Credit(5000);
 ///</code>
 ///</example>
 public void Credit(int amount)
 {
   Balance = amount + Balance;
 }

VS Code will respect that and would render something like enter image description here (Example taken from this site)

UPD Apparently, there is a similar question already

Upvotes: 3

Related Questions