Metals: Support Scaladoc template auto completion

[tanishiking]

Describe the solution you'd like
When I try to write scaladoc on method definitions with intellij-scala-plugin, it auto-completes the @param parameterName and @return based on the method definition below the cursor like this.

And this feature is available in TypeScript (VsCode + TSServer) too.

This is my favorite feature of intellij-scala-plugin and tsserver, and It would be awesome if the feature is available in metals as well:

• When the user type /**, show the popup for selecting completions
  
  
  
  • /** */ Scaladoc comment
  
  
• if the user hit the /** */ Scaladoc comment, auto-complete the scaladoc template based on the defined method just below the cursor.

For example,

/**| <- cursor here
def test(x: String, y: String): Boolean = {
  // ...
}

to

/**
  *
  * @param x | <- move cursor to here
  * @param y
  * @return
  */
def test(x: String, y: String): Boolean = {
  // ...
}

Describe alternatives you've considered

Currently, I write @param and @return by hand, but if metals auto-complete them, it would be easier to write detailed scaladoc, and potentially motivate people to write scaladoc.

Additional context

Search terms:
scaladoc, completion, docstring

[gabro]

@tanishiking thanks for proposing this. I agree it would be nice, and I estimate it shouldn't be hard to implement.

Moving forward, Metals could also suggest Scaladoc keywords when completing inside a Scaladoc comment. E.g.:

/**
  *  @param x ...
  *  @| <- suggest '@param', '@return' and other relevant keywords here
  */

or also

/**
  * @param |<- suggest 'a' and 'b' here
  */
def test(a: String, b: Boolean): Boolean = ???

A good starting point for implementing this is https://github.com/scalameta/metals/blob/3c7e1aa012ae012fa4ff6a84441c7e0c2824f0d8/mtags/src/main/scala/scala/meta/internal/pc/Completions.scala#L672

[tanishiking]

Moving forward, Metals could also suggest Scaladoc keywords when completing inside a Scaladoc comment.

That's a good idea!
I just developed rough implementation for scaladoc completion as a first step (currently works only on vscode). After brushing up the implements, I'm going to submit a PR.

• https://github.com/tanishiking/metals/commit/93f713b35a53c34d1770024421efa9f0ec095eb1
• https://github.com/tanishiking/metals-vscode/commit/0b7dfaeb18e2c9949cffdd42fe714c192bb546b6

[olafurpg]

@tanishiking thats cool! Are you sure those changes are necessary in the vscode extension? It should be possible to implement this feature within lsp.

[tanishiking]

Ah, we could trigger textDocument/completion on type /** by setting triggerCharacters on initializing here https://github.com/scalameta/metals/blob/93f713b35a53c34d1770024421efa9f0ec095eb1/metals/src/main/scala/scala/meta/internal/metals/MetalsLanguageServer.scala#L497, thank you for pointing it out!