在其 Visual Studio 工具提示中添加函数的使用信息

Question

我正在尝试在 Visual Studio 工具提示中添加有关如何使用我的函数的信息，类似于默认情况下每个 async function 的完成方式。

例子：

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

我尝试使用 <example> 标记，但此文本未显示在工具提示中。

official documentation 中没有任何其他标签的描述允许这样的事情。

async 函数是如何完成的，是否有可能对其他函数做同样的事情？

Answer 1

在我看来，这似乎是 VisualStudio 的一项特殊功能，仅适用于基于 Task 的方法。

Task reference code 在 XML 注释中没有显示任何与您应该调用它的方式相关的特殊内容：

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

我猜你唯一能做的就是使用<example> 和<code> 标签的组合。

 ///<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 会尊重这一点，并会呈现类似 （示例取自this site）

UPD 显然，有一个similar question already