Fix(49472): Added docs for Set and Map types

[Grubba27]

Fixes #49472

[sandersn]

Reading the rest of the comments, I feel the same way about nearly all of them: Some parts are valuable, the rest is redundant. @DanielRosenwasser or @andrewbranch what do you think about incomplete-but-interesting JSDoc vs complete-but-redundant?

[sandersn]

These comments are not very valuable, but I guess they're OK. In particular, "The key may be any javascript type" is generally true, but untrue for set, since K and V are declared on Map and will already be instantiated.

I'd vote to remove these lines, but let me know if you want to keep them.

[Grubba27]

I think almost the same. Most of these are MDN docs with some adjustments to make them easier to read while you are coding. Without the need for going to the docs. But if it makes more sense I would be delighted to adjust

[andrewbranch]

Personally I would delete any JSDoc that essentially just rewrites the code (or other in-scope JSDoc comments) as an English sentence. E.g.

@param key The key of the element to remove from the Map object.

• The key literally just the name of the parameter
• of the element I think that’s implied
• to remove just a synonym for delete which is the name of the method
• from the Map just the name of the type
• object c'mon 😄

[sandersn]

Please remove all the redundant comments based on @andrewbranch 's criterion.

[Grubba27]

Okay! I've done some adjusts with the jsdocs but I'm still not sure if they are all right especially with these two parts:

    /**
     * Returns a specified element from the Map object. If the value that is associated with the provided key is an object, then you will get a reference to that object and any change made to that object will effectively modify it inside the Map.
     * @param key
     * @returns Returns the element associated with the specified key. If no element is associated with the specified key, undefined is returned.
     */
    get(key: K): V | undefined;

makes sense to have the description and the return part?

also, my other question would be if makes sense having jsdocs like this one:

    /**
     * Removes the specified element.
     * @param key
     */
    delete(key: K): boolean;

because the method is already described itself. I'm a little bit confused

[andrewbranch]

1. I think you can just delete @param key if it doesn’t have a description.
2. For self-explanatory methods like delete, I don’t think it really needs the description, but I don’t have a strong opinion. However, delete should definitely have a @returns since it’s not at all obvious what that boolean means. I think it might read a little weird to have @param or @returns tags with no top-level description, so I’d be ok with leaving Removes the specified element in. @sandersn what do you think?

[andrewbranch]

A couple straggling @params but otherwise I think this looks good

[andrewbranch]

@params without a description don’t do anything, I’m pretty sure (same thing on Set)

[andrewbranch]

Thanks @Grubba27!