JS options when connecting the socket should be documented, and general JS documentation improvements

[srcrip]

Hey everyone,

I noticed that I can not seem to find official documentation for the options to socket connection in JavaScript. I think we really need to document this in ex doc. Maybe it's there and I just missed it?

Also I am interested in taking a crack at the JS documentation overall. I think there should be a new page in the docs that covers:

• the options to the live socket
• the exact functions available on the socket/hooks (I know this is covered in the section on js interop but I think it deserves its own section)
• some short blurb about the types, jsdoc vs TS types, and how you can add TS to a new phoenix project

I want to try writing this page but I'm not exactly sure of what some of those options on the live socket actually do. Also has anyone else thought about good ways to document JS functions in ex doc?

Addendum that I'm also curious about:

• the jsdoc types should have documentation in them, so it shows up in ides
• wasn't there some talk a while ago about moving the types into this repo itself? Did that ever happen? I'm on my phone right now so I can't easily find it.

[SteffenDE]

Hi @srcrip,

those are all very valid points you're raising here. Unfortunately the tl;dr is: neither Chris nor I actively do Typescript, therefore anything related to types isn't something we're working on. That said, we'd be happy to review PRs that do work on those topics. The main thing is that it shouldn't unnecessarily increase the maintenance burden on us "non Typescripties" though (see also #2892 (comment)).

I want to try writing this page but I'm not exactly sure of what some of those options on the live socket actually do.

If you work on a PR, we're happy to answer any questions coming up.

wasn't there some talk a while ago about moving the types into this repo itself? Did that ever happen? I'm on my phone right now so I can't easily find it.

There was #3022 where I mentioned that the types aren't in the repo. Concerning moving them here: if the types only document the public interface that'd be fine, I think. Currently https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/phoenix_live_view/index.d.ts also includes lots of private functions not meant to be accessed from the outside. A PR that moved the types into the repo and cleans them up would probably be something we would accept.

Before working on anything I'd wait for some feedback from @chrismccord though :)

[srcrip]

I think it would be a great improvement to move the public types into some kind of types.d.ts file here in the directory of the npm package (that would make it accessible when people use it in their editor). that's something I can work on. I'd personally love to see actual TypeScript itself, but I'm guessing that's probably unlikely?

As for the documentation, I'm unsure if we can really like generate anything from the types themselves. They're probably still going to have to be maintained in two places.

[begedin]

I would be happy to help out with any typing improvements, but currently don't have the capacity to do organising around it. So if there's any grunt work to be done, please reach out.

Perhaps what svelte is doingl but in a more limited capacity, would be a good way to do it. My understanding is, they rely on jsdoc annotations to generate a type declaration, while the codebase is vanilla js.