When hovering over the method, Metals shows method parameters in random order in scaladoc

[rtar]

Describe the bug

Metals does not keep the order of method parameters when rendering scaladoc.

How to reproduce

To reproduce, write a scaladoc for the method with several parameters like this:

  /** aaa
    * bbb
    *
    * @param param1 first parameter
    * @param param2 second parameter
    * @param param3 third parameter
    * @return useful number
    */
  def method(param1: Int, param2: String, param3: Boolean): Int

Then hover mouse over method signature to see scaladoc. The order of param1, param2 and param3 will be random. It complicates reading the code if named parameters are not used.

Root cause

The root cause is, likely, in MarkdownGenerator#toMarkdown method, where it does the following:

        "\n**Parameters**\n" + c.valueParams
          .map(tuple =>
            s"- `${tuple._1}`: " + blocksToMarkdown(tuple._2.blocks)
          )
          .mkString

As c.valueParams is a Map then, the order becomes random.

Potential fix

The fix could be reworking Comment#valueParams to store ordering information after parsing the parameters.

Expected behavior

No response

Operating system

Linux

Editor/Extension

VS Code

Version of Metals

v1.23.0

Extra context or search terms

No response

[tgodzik]

Thanks for reporting! Hopefully, this should not be hard to fix.

[jkciesluk]

closing as completed in https://github.com/scalameta/metals/pull/5414