Documentation output missing sections, lacking formatting, lacking newlines.

[erichiller]

Issue Description

Documentation output for my own code is lacking sections and formatting, I've tried in several different (new) projects and it always only shows the summary block and never properly formats newlines. I thought this was just a long standing bug that everyone experienced, but after looking through some issues, I saw that many others seem to have much more detailed and well formatted output. Is my output the expected documentation output?

Steps to Reproduce

Create any documentation.

Expected Behavior

Something like #1918 (comment)

Actual Behavior

Logs

OmniSharp log

Post the output from Output-->OmniSharp log here

C# log

Post the output from Output-->C# here

Environment information

VSCode version: 1.48.2
C# Extension: 1.23.2

Dotnet Information

.NET Core SDK (reflecting any global.json): Version: 3.1.401 Commit: 39d17847db

Runtime Environment:
OS Name: Windows
OS Version: 10.0.19041
OS Platform: Windows
RID: win10-x64
Base Path: C:\Program Files\dotnet\sdk\3.1.401\

Host (useful for support):
Version: 3.1.7
Commit: fcfdef8d6b

.NET Core SDKs installed:
3.1.102 [C:\Program Files\dotnet\sdk]
3.1.302 [C:\Program Files\dotnet\sdk]
3.1.401 [C:\Program Files\dotnet\sdk]

.NET Core runtimes installed:
Microsoft.AspNetCore.App 3.1.2 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 3.1.6 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 3.1.7 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.NETCore.App 3.1.2 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 3.1.6 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 3.1.7 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.WindowsDesktop.App 3.1.2 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 3.1.6 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 3.1.7 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]

To install additional .NET Core runtimes or SDKs:
https://aka.ms/dotnet-download

Visual Studio Code Extensions

Extension	Author	Version
better-align	wwm	1.1.6
csharp	ms-dotnettools	1.23.2
docomment	k--kato	0.1.18
errorlens	usernamehw	3.2.1
gitignore	codezombiech	0.6.0
graphql-for-vscode	kumar-harsh	1.15.3
hexeditor	ms-vscode	1.2.1
jsdoc-markdown-highlighting	bierner	0.0.1
markdown-all-in-one	yzhang	3.3.0
msbuild-project-tools	tintoy	0.3.8
path-intellisense	christian-kohler	2.2.1
powershell-preview	ms-vscode	2020.7.0
rainbow-csv	mechatroner	1.7.1
remote-ssh-edit	ms-vscode-remote	0.51.0
selected-lines-count	gurumukhi	1.4.0
sqltools	mtxr	0.23.0
svg	jock	1.3.9
theme-karyfoundation-themes	karyfoundation	20.0.3
todo-tree	Gruntfuggly	0.0.178
vscode-docker	ms-azuretools	1.5.0
vscode-eslint	dbaeumer	2.1.8
vscode-great-icons	emmanuelbeziat	2.1.52
vscode-json5	mrmlnc	1.0.0
vscode-scss	mrmlnc	0.9.0
vscode-scss-formatter	sibiraj-s	2.0.2
vscode-solution-explorer	fernandoescolar	0.3.11
vscode-yaml	redhat	0.10.1

[jmarolf]

@333fred do you think this is related to the changes you made recently?

[333fred]

It's likely related. The formatting I implemented was best-effort, I have no doubt there is room for improvement in the tagged-text->markdown implementation.

[333fred]

In particular, the issues with the newlines are a translation issue: VSCode uses markdown to render the documentation, and single newlines in markdown do not actually signal the start of a new line. There's no particularly great solution here: inserting an extra newline in the text during translation will often end up looking terrible itself, as it introduces a large amount of whitespace inbetween each line. The reason line 5 isn't . As to parameters being displayed in quickinfo, this is not what VS does, as Dustin showed. The hover implementation in omnisharp now just calls into roslyn, so if you want parameter info to be displayed that would need to be a roslyn feature request, not an omnisharp feature request.

[333fred]

And actually, it looks like the newline thing is a roslyn issue as well. This is what VS shows for newlines in doc comments:

[gregg-miskelly]

This is not my area of expertise, but I think this is "by design". If you want line breaks, you need to use <para>. Example:

        /// <summary>
        /// Line1
        /// <para>Line2</para>
        /// </summary>

[erichiller]

To add to the markdown double newline required to output a single newline, there is an alternative - double space at the end of the line. So that would be a more aesthetically pleasing option. VSCode obeys this rule, so a simple solution to newlines could be replace all <content>\r?\n with <content> \n.

The second part of the issue, outside of lacking newlines, is that there are no section headings as I've seen in past issues/comments ( #1918 (comment) and #1057 (comment) )

[erichiller]

I see now (I'm not sure if it was like this in prior versions), that when completing the parameters for a function, the output is displayed "correctly" with line breaks, and the parameter list.

When mousing over the method however (or Ctrl+space):

Here is the actual comment/code doc:

[333fred]

As mentioned, the latter behavior is the correct behavior. Omnisharp now uses roslyn's built-in handling for quick info. In xml comments in general, if you want a newline you should use a para tag.