Unclear documentation of query vs. observer options

[d-leeg]

The documentation of query options does not clearly state, except in rare occasions (most notably gcTime and staleTime), which options are at the level of the query (i.e., are associated with a given queryKey cache entry), and which are at the level of the observer (i.e., may be different for different observers of the same queryKey cache entry); moreover, for options that are at the query level, the documentation should clearly state how different values specified by different calls to useQuery and its friends get reconciled to a single value associated with the query.

For example, while most developers would easily guess that queryFn is at the query level, it is unclear what happens if different calls to useQuery specify a different queryFn for the same key: is the queryFn set only by the first call that uses that key (and thus creates the query), and subsequent values ignored, or is it updated every time it is given? It turns the latter is true, but unfortunately undocumented.

The situation is worse with other options where it is much less clear to a developer not familiar with the inner-workings of the library. For example are retryDelay or refetchOnWindowFocus at the query level or the observer level?

It is quite clear that early on, a decision has been made that the
API of the library would not make explicit the distinction between the data associated with a given cache entry, (internally called a "query") and an observer of this data (internally called a "queryObserver"). We thus have a single main entry point to create both in the form of the useQuery hook. I fully understand this decision, but in order to use the library with confidence the documentation must address this distinction.