Improve Hover markdown on 'await' keyword

src/Features/Core/Portable/FeaturesResources.resx

@@ -668,7 +668,7 @@ Do you want to continue?</value>
     <value>&lt;Pending&gt;</value>
   </data>
   <data name="Awaited_task_returns_0" xml:space="preserve">
-    <value>Awaited task returns '{0}'</value>
+    <value>Awaited task returns {0}</value>
   </data>
   <data name="Awaited_task_returns_no_value" xml:space="preserve">
     <value>Awaited task returns no value</value>

src/Features/LanguageServer/Protocol/Extensions/ProtocolConversions.MarkdownContentBuilder.cs

@@ -0,0 +1,53 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using Microsoft.CodeAnalysis.PooledObjects;
+
+namespace Microsoft.CodeAnalysis.LanguageServer;
+
+internal static partial class ProtocolConversions
+{
+    private readonly ref struct MarkdownContentBuilder
+    {
+        private readonly ArrayBuilder<string> _linesBuilder;
+
+        public MarkdownContentBuilder()
+        {
+            _linesBuilder = ArrayBuilder<string>.GetInstance();
+        }
+
+        public void Append(string text)
+        {
+            if (_linesBuilder.Count == 0)
+            {
+                _linesBuilder.Add(text);
+            }
+            else
+            {
+                _linesBuilder[^1] = _linesBuilder[^1] + text;
+            }
+        }
+
+        public void AppendLine(string text = "")
+        {
+            _linesBuilder.Add(text);
+        }
+
+        public bool IsLineEmpty()
+        {
+            return _linesBuilder is [] or [.., ""];
+        }
+
+        public string Build(string newLine)
+        {
+            return string.Join(newLine, _linesBuilder);
+        }
+
+        public void Dispose()
+        {
+            _linesBuilder.Free();
+        }
+    }
+}

src/Features/LanguageServer/Protocol/Extensions/ProtocolConversions.cs

@@ -30,11 +30,13 @@
 
 namespace Microsoft.CodeAnalysis.LanguageServer
 {
-    internal static class ProtocolConversions
+    internal static partial class ProtocolConversions
     {
         private const string CSharpMarkdownLanguageName = "csharp";
         private const string VisualBasicMarkdownLanguageName = "vb";
         private const string SourceGeneratedDocumentBaseUri = "source-generated:///";
+        private const string BlockCodeFence = "```";
+        private const string InlineCodeFence = "`";
 
 #pragma warning disable RS0030 // Do not use banned APIs
         private static readonly Uri s_sourceGeneratedDocumentBaseUri = new(SourceGeneratedDocumentBaseUri, UriKind.Absolute);
@@ -844,40 +846,65 @@ public static LSP.MarkupContent GetDocumentationMarkupContent(ImmutableArray<Tag
                 };
             }
 
-            var builder = new StringBuilder();
-            var isInCodeBlock = false;
+            using var markdownBuilder = new MarkdownContentBuilder();
+            string? codeFence = null;
             foreach (var taggedText in tags)
             {
                 switch (taggedText.Tag)
                 {
                     case TextTags.CodeBlockStart:
-                        var codeBlockLanguageName = GetCodeBlockLanguageName(language);
-                        builder.Append($"```{codeBlockLanguageName}{Environment.NewLine}");
-                        builder.Append(taggedText.Text);
-                        isInCodeBlock = true;
+                        if (markdownBuilder.IsLineEmpty())
+                        {
+                            // If the current line is empty, we can append a code block.
+                            codeFence = BlockCodeFence;
+                            var codeBlockLanguageName = GetCodeBlockLanguageName(language);
+                            markdownBuilder.AppendLine($"{codeFence}{codeBlockLanguageName}");
+                            markdownBuilder.AppendLine(taggedText.Text);
+                        }
+                        else
+                        {
+                            // There is text on the line already - we should append an in-line code block.
+                            codeFence = InlineCodeFence;
+                            markdownBuilder.Append(codeFence + taggedText.Text);
+                        }
                         break;
                     case TextTags.CodeBlockEnd:
-                        builder.Append($"{Environment.NewLine}```{Environment.NewLine}");
-                        builder.Append(taggedText.Text);
-                        isInCodeBlock = false;
+                        if (codeFence == BlockCodeFence)
+                        {
+                            markdownBuilder.AppendLine(codeFence);
+                            markdownBuilder.AppendLine(taggedText.Text);
+                        }
+                        else if (codeFence == InlineCodeFence)
+                        {
+                            markdownBuilder.Append(codeFence + taggedText.Text);
+                        }
+                        else
+                        {
+                            throw ExceptionUtilities.UnexpectedValue(codeFence);
+                        }
+
+                        codeFence = null;
+
                         break;
                     case TextTags.LineBreak:
                         // A line ending with double space and a new line indicates to markdown
                         // to render a single-spaced line break.
-                        builder.Append("  ");
-                        builder.Append(Environment.NewLine);
+                        markdownBuilder.Append("  ");
+                        markdownBuilder.AppendLine();
                         break;
                     default:
-                        var styledText = GetStyledText(taggedText, isInCodeBlock);
-                        builder.Append(styledText);
+                        var styledText = GetStyledText(taggedText, codeFence != null);
+                        markdownBuilder.Append(styledText);
                         break;
                 }
             }
 
+            var content = markdownBuilder.Build(Environment.NewLine);
+
             return new LSP.MarkupContent
             {
                 Kind = LSP.MarkupKind.Markdown,
-                Value = builder.ToString(),
+                Value = content,
             };
 
             static string GetCodeBlockLanguageName(string language)

src/Features/LanguageServer/ProtocolUnitTests/Hover/HoverTests.cs

@@ -428,6 +428,34 @@ void A.AMethod(int i)
             Assert.Equal(expectedMarkdown, results.Contents.Value.Fourth.Value);
         }
 
+        [Theory, CombinatorialData, WorkItem("https://github.com/dotnet/vscode-csharp/issues/6577")]
+        public async Task TestGetHoverAsync_UsesInlineCodeFencesInAwaitReturn(bool mutatingLspWorkspace)
+        {
+            var markup =
+@"using System.Threading.Tasks;
+class C
+{
+    public async Task<string> DoAsync()
+    {
+        return {|caret:await|} DoAsync();
+    }
+}";
+            var clientCapabilities = new LSP.ClientCapabilities
+            {
+                TextDocument = new LSP.TextDocumentClientCapabilities { Hover = new LSP.HoverSetting { ContentFormat = [LSP.MarkupKind.Markdown] } }
+            };
+            await using var testLspServer = await CreateTestLspServerAsync(markup, mutatingLspWorkspace, clientCapabilities);
+            var expectedLocation = testLspServer.GetLocations("caret").Single();
+
+            var expectedMarkdown = $@"{string.Format(FeaturesResources.Awaited_task_returns_0, "`class System.String`")}  
+";
+
+            var results = await RunGetHoverAsync(
+                testLspServer,
+                expectedLocation).ConfigureAwait(false);
+            Assert.Equal(expectedMarkdown, results.Contents.Value.Fourth.Value);
+        }
+
         private static async Task<LSP.Hover> RunGetHoverAsync(
             TestLspServer testLspServer,
             LSP.Location caret,