[RFC] Is the purpose of `*_api.cu` tests in CUB to only test API examples?

I had the discussion below with @gonidelis on the conventions of `*_api.cu` files, which in my understanding are only containing tests of API examples appearing in the documentation.

In order to make progress on some critical PRs, I will not block them on non-API examples being added to those files, but we should agree on a guideline on where to put tested API examples for the documentation, which are not intended to be functional tests. This decision should then be documented in the CUB developer guide.

> 1. doesn't have to be an example to go under the `_api.cu` test. It's literally what the name suggest, an API test, not an example (which the file name doesn't even suggest).

This is contrary to my understanding. `_api.cu` contain only API examples which are referenced from the documentation. They do not contain any functional tests.

Functional tests are always in files like `catch2_test_device_algorithmname.cu` (with some variations). You also added tests named `catch2_test_device_algorithmname_env.cu`, which test whether the handling of the execution environment works correctly, with little or no focus on algorithmic correctness.

Please elaborate why we need to break the convention now, or where it has been broken before.

_Originally posted by @bernhardmgruber in https://github.com/NVIDIA/cccl/pull/8979#discussion_r3264571829_