Formatting for method descriptions is not preserved

[bobalicious]

Summary

When description comments are added to Apex methods, the resulting tool-tip does not preserve formatting, nor does it appear to provide any mechanism for stating that certain formatting should apply.

Steps To Reproduce:

1. Define an Apex class with method that includes a documentation comment with some form of formatting. For example:

/**
* States that the next method definition is expected to be called in the order it appears.
*
* If a method is subsequently called out of order, will fail the test.
*
* Calling 'verify' will check that all expectations have been met, failing the test if not.
*
* 'Expectations' take lower priority than 'whens' (I.E. if a matching 'when' is defined at call time, then it will match that over the next 'expect').
*
* Define in the format:
* expects()
*       .method( 'methodName' )
*       .withParameter( 'parameterValue' )
*       .returning( 'theValueItShouldReturn' )
*/

1. In another method, define a call to that method, and hover over the method call

Expected result

Formatting of the documentation comment to be preserved. Or options exist for stating the formatting required.

Actual result

Formatting of the documentation comment is not preserved.

Additional information

VS Code Version: Version 1.30.0 (1.30.0)

SFDX CLI Version: sfdx-cli/7.69.0-1101929cd1 darwin-x64 node-v12.18.3

OS and version: macOs Catalina 10.15.2

[smaddox-sf]

Hi @bobalicious - Thanks for submitting this and including the screenshots - very helpful. Is your objection that the extra whitespace is removed? (extra lines & indents).

[bobalicious]

Thanks for the response.

You are correct, in essence.

My objection is the fact that there are no options for providing some form of formatting.

Having had a look around, the convention in other languages appears to be to either:

• Preserve the whitespace as is presented in the comment
• Remove the extra whitespace and allow simple HTML tags in order to state formatting (e.g. p, br, pre, ul, ol, li)

I would personally prefer the whitespace to be preserved (as this means the doc comments are readable when viewed inline, in the code itself), though I'd be happy with HTML tags or some other markup, as long as it's possible to have some formatting options.