TLDR: This MR adds a brief mention of the behavior of cache function right at the top of the documentation, in the "Caveats" section, which feels like the right place for such "heads up, confirm you're using it right" piece of information.

"Explicit is better than implicit." — The Zen of Python (Tim Peters)

Recently we were working on enhancing reliability for our website, specifically revisiting what and how efficiently we are caching.

After a bunch of investigations and trying things out, we found out that we were not using the cache function correctly. It was added some time ago and we were passing objects in params instead of primitives. But since the documentation doesn't really directly mentions it anywhere (only deep down in the troubleshooting section, where it mentions Object.is comparison briefly without explaining it too much), we didn't even know we are using it wrong until we started targeted debugging.

This whole investigation and debugging flow sparked some ideas and we wanted to help future engineers like ourselves to not end up in a similar situation by misreading/misunderstanding the documentation. So this MR adds a brief mention of the behavior of cache function right at the top of the documentation, in the "Caveats" section, which feels like the right place for such "heads up, confirm you're using it right" piece of information.