withSelect documentation needs attention

[rdm]

Describe the bug
In https://developer.wordpress.org/block-editor/packages/packages-data/#withSelect the Parameters subheading does not document any parameters which are touched on in the surrounding text, nor does the surrounding text seem to have any relationship to the documentation about parameters.

Likewise, in https://developer.wordpress.org/block-editor/packages/packages-data/ there's example code that involves withSelect but it does not document data flow. And, in particular, two functions want an argument which is an object which has a 'currency' property, but nothing about that example shows where those objects would be coming from (for example, I haven't noticed such an object being created in any of the other examples on that page).

Both of these issues suggest copy&paste errors, but someone more qualified than I should take a look at these items, to declare what should be happening.

To reproduce
Visit the above mentioned pages.

Expected behavior
The withSelect documentation at the above pages should provide clear and concise descriptions of the behavior of functions generated by withSelect: (What happens in what order, when the resulting function is used?)

[rdm]

To expand on the above:

basically, the current documentation on withSelect (and, other methods) looks like a developer's notes from an early stage of development.

1. withSelect takes an argument which is a function. This function argument in turn will be supplied three arguments. Those arguments are not documented. And only two of them have suggested names.

2. the descriptive text for withSelect describe the implementation, but do not link to the implementation.

This is not adequate documentation, though parts of it might be useful. To work with the system as it is, the user must be familiar with the underlying components (react, redux, perhaps backbone, the wordpress REST api, etc.) and spend quite a bit of time performing experiments to determine which parts of what they know about pieces of the infrastructure are relevant and which parts are irrelevant.

[ryanwelcher]

@tomdevisser this is the issue we discussed.