[cmake-developers] FindThreads module documentation needs some work

[Alan W. Irwin]

In my opinion [the latest documentation of the FindThreads
module](https://cmake.org/cmake/help/latest/module/FindThreads.html)
needs some work.  Specifically please deal with the following documentation issues.

* 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 it would be good to have that purpose 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, learning to use this module
properly on both Linux and Mac OS X for PLplot and another project I
have been working on has been much more work than I expected (i.e.,
instead of relying on documentation I had to analyze the CMake code in
this module to figure out what was going on).

I would be willing to repeat all the above in a bug report, but
instead of doing that I hope someone here is willing to step forward
with fixups for the above simple documentation issues in a timely
manner so there is no bug triage burden for these fixups.

Alan
__________________________
Alan W. Irwin

Programming affiliations with the FreeEOS equation-of-state
implementation for stellar interiors (freeeos.sf.net); the Time
Ephemerides project (timeephem.sf.net); PLplot scientific plotting
software package (plplot.org); the libLASi project
(unifont.org/lasi); the Loads of Linux Links project (loll.sf.net);
and the Linux Brochure Project (lbproject.sf.net).
__________________________

Linux-powered Science
__________________________