Confusing description of Pick mapped type #25976

Search Terms:
confusing, pick, description

Problem:

Typescript has so much great functionality, but it gets hard to comprehend them for a not very experienced developer if the descriptions are confusing. Example is the description of Pick mapped property.

Actual behavior:
The description of type Pick<T, K extends keyof T> = { [P in K]: T[P]; }says:

From T pick a set of properties K.

However, the way I have been assuming the description at first, before I discovered the truth, was: we need to supply a defined type / interface as a first parameter and another defined type / interface as a second parameter, i.e.:

type ParamOne = {
  one: string;
  two: string;
  three: number;
}

type ParamTwo = {
  two: string;
  three: number;
}

type Picked = Pick<ParamOne, ParamTwo> // error

This does not work and would lead to the error, because the second parameter should contain the keys of ParamOne delineated with |, even though the description says a set of !properties K, not a set of !keys K. I understand that the word propertiesprobably refers to T, but hear me out.

So, the correct way to get type { two: string, three: number }would be this way:

type Picked = Pick<ParamOne, 'two' | 'three'>

Expected behavior:
Therefore, instead of having:

From T pick a set of properties K.

as a description, would not it be more clearer, especially for the not very experienced developers, if the description would change to:

From T pick a set of properties whose keys are K.

?

I understand that there is also the definition of the type available for us which looks this way:

type Pick<T, K extends keyof T> = { [P in K]: T[P]; }

But for me as a person who has not been working with typescript for a lot of time, this looked like very complicated and unfamiliar syntax when perceived altogether in a single line, even though some parts, like the one to the right, where the object property is being assigned, were more or less readable.

I hope that future generations of typescript users won't be struggling with mapped types the way I have been and this correction might improve the situation. Thank you!