Show documentation on hover and completion

[PgBiel]

Closes #72 (still WIP)

Right now, neither feature works at all in VSCode for some reason. I'm not sure if this is a problem with the extension or with server/client capabilities or something else, but currently, with this PR's changes, the language server is just returning null for any hover or completion with documentation in VSCode, meaning items with documentation are just not suggested / have no hover anymore. I'll try to investigate, but for now, all screenshots below use the Zed extension.

EDIT: It works in VSCode. Turns out I wasn't telling VSCode to use my build, so it was using an outdated version of the LSP. Whoops :)

In addition to trying to get the VSCode extension to work, I'd like to implement at least the following changes:

• Creating a proper doc comment structure which separates main doc body from contracts (right now it's just a plain string). This will allow us to only send the doc body on completions instead of also including contracts. In addition, it allows us to properly structure contracts visually on hover.
  • To be honest, I'm not entirely sure whether we should omit contracts from completions as long doc strings can happen anyway, and would be shown separately. But I think this is a good heuristic for now and keeps the list of completions more compact.
• Automatically remove common indentation from the doc comment body.
• We could also consider adding function documentation to signature help; I'll leave this as a separate and optional task (although it's probably quite trivial, but would need some additional testing).
  • Done, although it's currently missing docs for individual parameters, but that'd need some additional work to parse @param docs.

Future work

• Parse param docs (e.g. @param value `The requested value.` )

Screenshots

VSCode

Unfortunately, VSCode doesn't support showing documentation directly on completions; however, they can be manually shown with Ctrl/Cmd + I:

Zed

[pherrymason]

I'm concerned that this work will need to be replicated and adapted in the branch search_on_astB, which takes a different approach on parsing and searching.
Do you feel brave enough doing the PR on that branch?

[pherrymason]

Thinking it better, is ok if you do it on main branch, it will serve me as a base anyway, PR very welcomed.
Anyway autocomplete system is not yet implemented on that other branch..

[PgBiel]

I'm concerned that this work will need to be replicated and adapted in the branch search_on_astB, which takes a different approach on parsing and searching.
Do you feel brave enough doing the PR on that branch?

I could give it a shot at some point, but to be honest my work here is (comparatively) pretty simple - I just traverse top-level nodes in order and attach each doc comment to the node that immediately follows the doc comment. The rest (hover, completion) just reads the attached doc comments from the Indexable structures. So it wouldn't be that much of a loss to completely redo the parsing part for the new branch as needed. That is, the PR could safely land on main, and then the new branch could be rebased by just ignoring my changes on the parsing part (which uses the tree-sitter CST in principle).

[PgBiel]

Should be ready to go 😎

Feel free to give it a spin.

[pherrymason]

Is this because of how you decide which doc comment you assign to a symbol? (Las doc block parsed belongs to next identified symbol)

[PgBiel]

In part, yes: I'd have to replicate my code to detect and assign doc comments in the struct parsing function as well in order to accept doc comments inside the struct, i.e. to accept something like

struct Name {
  <* doc *>
  int a;
}

But also, I didn't do that because it doesn't compile (through c3c), even though the tree-sitter grammar accepts it.

We could, of course, just copy and paste the struct's own docs to all of its members, but that doesn't feel ideal, at least not at the moment.

[pherrymason]

Great work! Thank you