FindThreads module documentation needs to be updated
The latest documentation of the FindThreads module](https://cmake.org/cmake/help/latest/module/FindThreads.html) should be updated. Here is a list of issues I have identified with that documentation.
-
Threads_FOUND needs documentation. And that needs to be done at the top of the documentation as typically happens with other modules where a <MODULE_NAME>_FOUND variable is being set on a successful find.
-
CMAKE_HAVE_THREADS_LIBRARY needs documentation. I suspect the value of this variable (set in the module but otherwise not used there) has been historically useful for those module users who have figured out its purpose, but that purpose should be documented.
-
The CMAKE_THREAD_LIBS_INIT variable and corresponding Threads::Threads INTERFACE_LINK_LIBRARIES target property is the empty string for the case when the (Posix) threads functions are provided by the C library. According to a second-hand report I received this case happens on Mac OS X (at least for MacPorts). Therefore, please document this expected result for that important use case.
-
Finally, for that same important use case THREADS_PREFER_PTHREAD_FLAG is completely ignored, and that should be documented as well.
Because of these documentation issues using this module is much more difficult than it needs to be.
For reference this issue was initially discussed at https://cmake.org/pipermail/cmake-developers/2019-October/031246.html.