dotnet / dotnet/vscode-csharp

Documentation popup doesn't display C# XML documentation properly

Open
#5,670 3 comments 19 reactions 0 assignees View on GitHub
OmniSharp
Dominant language
TypeScript
Stars
3.1k
Forks
737
Avg merge
18h 40m
Merged PRs (30d)
31

Description

C# XML doc comments don't get rendered as they deserved by VsCode's inline doc popup. Namely:

- The Examples section is missing;
- The See Also section is missing;
- The exceptions are listed, but without documentation;
- Lists are poorly displayed;
- Tables are poorly — let's stay polite — displayed;
- The generic type parameter in the inline code snippets is missing (see below);
- Inline code snippets are not rendered in monospace font;
- Code snippets are not highlighted;

## Code

```cs
class Example {
/**


This is a summary paragraph.


This is another summary paragraph.




This is a remark paragraph.


Let's now make a simple list:


One
Two
Three


Let's now make a paragraph list:




This is a one paragraph.




This is a two paragraph.




This is a three paragraph.




Let's now make a definition list:



One
The first term defined.


Two
The second term defined.


Three


The third term defined.


This one is defined over two paragraphs.





There are also number lists:


One
Two
Three


There are also table lists:



Action
Description
Power Consumption


Forward
Move forwards in a straight line.
50W


Backward
Move backwards in a straight line.
50W


RotateLeft
Rotate to the left.
30W


RotateRight
Rotate to the right.
30W


Dig
Tells the robot to dig and obtain a soil sample.
800W



Let's also use with some inline new Example().Sample<int>(0); code.




This is a T paragraph.
The type refers to the type of the parameter .




This is a parameter paragraph.




This is a return paragraph.




This is an exception paragraph.




This is another exception paragraph.




Let's also use with some block code:


int f() {
return new Example().Sample<int>(0);
}




Another example, this one is escaped with CDATA:

(0);

return b;
}
]]>



**/
public int Sample(T x) => 0;
}
```

## Expected

> This is a summary paragraph.
>
> This is another summary paragraph.
>
> ### Returns
>
> This is a return paragraph.
>
> ### Exceptions
>
> #### ArgumentException
>
> This is an exception paragraph.
>
> #### DllNotFoundException
>
> This is another exception paragraph.
>
> ### Remarks
>
> This is a remark paragraph.
>
> Let's now make a simple list:
>
> - One
> - Two
> - Three
>
> Let's now make a paragraph list:
>
> - This is a one paragraph.
>
> - This is a two paragraph.
>
> - This is a three paragraph.
>
> Let's now make a definition list:
>
>


>
One
The first term defined.
>
Two
The second term defined.
>
Three

The third term defined.

This one is defined over two paragraphs.


>

>
> There are also number lists:
>
> 1. One
> 2. Two
> 3. Three
>
> There are also table lists:
>
> | Action | Description | Power Consumption |
> |:---- |:---- |:---- |
> | Forward | Move forwards in a straight line. | 50W |
> | Backward | Move backwards in a straight line. | 50W |
> | RotateLeft | Rotate to the left. | 30W |
> | RotateRight | Rotate to the right. | 30W |
> | Dig | Tells the robot to dig and obtain a soil sample. | 800W |
>
> Let's also use with some inline `new Example().Sample(0);` code.
>
> ### Examples
>
> Let's also use with some block code:
>
> ```cs
> int f() {
> return new Example().Sample(0);
> }
> ```
>
> Another example:
>
> ```cs
> int f() {
> var a = new Example();
> var b = a.Sample(0);
>
> return b;
> }
> ```
>
> ### See Also
>
> - `Example`

## Actual

> This is a summary paragraph.
>
> This is another summary paragraph.
>
> This is a remark paragraph.
>
> Let's now make a simple list:
>
> - One
>
> - Two
>
> - Three
>
> Let's now make a paragraph list:
>
> - This is a one paragraph.
>
> - This is a two paragraph.
>
> - This is a three paragraph.
>
> Let's now make a definition list:
>
> - One – The first term defined.
>
> - Two – The second term defined.
>
> - Three –\
> The third term defined.\
> This one is defined over two paragraphs.
>
> There are also number lists:
>
> 1. One
>
> 2. Two
>
> 3. Three
>
> There are also table lists:
>
> Action – Description – Power Consumption –
>
> Forward – Move forwards in a straight line. – 50W –
>
> Backward – Move backwards in a straight line. – 50W –
>
> RotateLeft – Rotate to the left. – 30W –
>
> RotateRight – Rotate to the right. – 30W –
>
> Dig – Tells the robot to dig and obtain a soil sample. – 800W –
>
> Let's also use with some inline new Example().Sample(0); code.
>
> Returns:
>
> This is a return paragraph.
>
> Exceptions:
>
> ArgumentException\
> DllNotFoundException

----

I'm using `"csharp.semanticHighlighting.enabled": true`\
VsCode 1.77.3, commit 704ed70d4fd1c6bd6342c436f1ede30d1cff4710\
C# extension 1.25.4

----

See also #3884

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.