search

phoenixframework / phoenix_live_view

Rich, real-time user experiences with server-rendered HTML
https://hex.pm/packages/phoenix_live_view
MIT License
6.21k stars 930 forks source link

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

Open srcrip opened 3 months ago

srcrip commented 3 months ago

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:

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:

SteffenDE commented 2 months ago

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 https://github.com/phoenixframework/phoenix_live_view/pull/2892#issuecomment-1896638445).

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 https://github.com/phoenixframework/phoenix_live_view/pull/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 commented 1 month ago

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 commented 1 month ago

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.