socket.io icon indicating copy to clipboard operation
socket.io copied to clipboard

Published 20 hours ago • verified publisher icon socketio

comment: write js docs in on

Open nayounsang opened this issue 1 year ago • 3 comments

The kind of change this PR does introduce

  • [ ] a bug fix
  • [x] a new feature
  • [ ] an update to the documentation
  • [ ] a code change that improves performance
  • [x] other

Current behavior

  • About socket-io-client-emitter/Emitter on method.
  • It was difficult for us to know what the reserved event names were without looking at the docs.

New behavior

image

  • I thought it would be better to use JSDoc without changing the types. This is because there is an advantage of auto-completion when using union, etc., but developers often use custom event names, so I thought the type could actually cause confusion.
  • So I used JSDoc. If the user checks the JSDoc, they can see the scheduled event name and its brief description. If developers are curious about more, I have linked the docs.

Other information (e.g. related issues)

  • If you want to edit, change or delete content, please always leave a comment.
  • I've only written about on at the moment, so if you think it would be good to write about something else as well, please let me know.

nayounsang avatar Sep 25 '24 04:09 nayounsang

Hi! Thanks a lot for your PR.

I'm not sure this is right though, as the emitter provided by the @socket.io/component-emitter is used in several places, not just for the Socket object of the socket.io-client package.

Another possibility would be to override the on method in the Socket class, and add the improved documentation there. What do you think?

darrachequesne avatar Oct 23 '24 09:10 darrachequesne

@darrachequesne There is a way like that! I also think this is better.

nayounsang avatar Oct 23 '24 12:10 nayounsang

Hi. I commit this. Is this correct what you said?

  • I was confused about where to place the overridden method. First of all, since it is a new change, I placed it at the very bottom.
  • I am wondering how to use the ReversedEvents type defined as a generic in the Emitter. Basically, it simply inherits EventMaps, so I created a new interface: interface ReservedEvents extends EventsMap {}. However, there remains a question as to whether this will ensure a consistent type with the on of the Emiiter in the future.

If it doesn't fit your intention, or if you have any comments, please let me know!

nayounsang avatar Oct 23 '24 13:10 nayounsang