Add JSDoc for hook examples

[RodolfoSilva]

@chrismccord, reopened this which was previously incorporated into #2892 PR

---

I've added JSDoc annotations to the Hook usage examples in order to enhance IDE autocomplete functionality. Often, developers find themselves referring back to the documentation to recall a Hook's structure and its associated functions. Embedding type documentation directly within the code streamlines this process, offering a more efficient development experience.

[chrismccord]

Will this work for markdown and elixir docs in the editor? I'm happy to see us JSDoc the source files, but including it in the Elixir docs is out of place unless it really provides robust integration with ls servers/editors at large

[RodolfoSilva]

Yes, this is fully compatible with all editors. Im use this approach with a clean vscode version. Without any additional plugin.

This turn possible to use the autocomplete when we are developing a new hook.

[SteffenDE]

This does indeed help editors like VSCode to properly suggest completions when working with hooks.

Old:

New:

The completions come from https://www.npmjs.com/package/@types/phoenix_live_view though, not directly from the LV js code.

[rhcarvalho]

Oh yeah this worked for me on an existing project. Indeed helps improve autocomplete in VSCode (perhaps other editors too depending on setup/config).

I wish this was opt-in and the least intrusive as possible.

I tried a few other options like putting //@ts-check on top of the file (https://code.visualstudio.com/docs/languages/javascript#_type-checking), installing the @types/phoenix_live_view using npm, and defining the type on LiveSocket. They all bring something, but I'm not particularly satisfied inflicting the changes on everyone.

Ideally there'd be some one-liner we could include in the phx.new app.js template or docs. The //@ts-check comment is the closest one so far, but it doesn't give good autocomplete suggestions for Hooks the way we tend to write them.

[SteffenDE]

Thank you for the bump. If there is a better way to solve it we might revisit this later, but I think these changes are fine.

[RodolfoSilva]

@chrismccord could you check out @SteffenDE demonstration?

I've tested this on:

• VSCode
• SublimeText
• Intellij
• Zed