ProcessorCount: Update documentation

Changes:
- Module documentation is sorted into a function description and a note
  section is added where cmake_host_system_information() is mentioned as
  an alternative.
- Module usage example is moved to a titled section at the end for
  better readability.
- Instead of mentioning the physical processors count, the logical
  processors is used as this is what is most likely wanted in most cases
  and also all the used commands in this module return this number.
- Function's code style is synced a bit across the code base.

Modules/CMakeFindCodeBlocks.cmake

@@ -18,7 +18,7 @@ include(${CMAKE_CURRENT_LIST_DIR}/CMakeExtraGeneratorDetermineCompilerMacrosAndI
 set(_CMAKE_CODEBLOCKS_INITIAL_MAKE_ARGS "")
 
 include(ProcessorCount)
-processorcount(_CMAKE_CODEBLOCKS_PROCESSOR_COUNT)
+ProcessorCount(_CMAKE_CODEBLOCKS_PROCESSOR_COUNT)
 
 # Only set -j if we are under UNIX and if the make-tool used actually has "make" in the name
 # (we may also get here in the future e.g. for ninja)

Modules/CMakeFindEclipseCDT4.cmake

@@ -68,7 +68,7 @@ _find_eclipse_version()
 set(_CMAKE_ECLIPSE_INITIAL_MAKE_ARGS "")
 
 include(ProcessorCount)
-processorcount(_CMAKE_ECLIPSE_PROCESSOR_COUNT)
+ProcessorCount(_CMAKE_ECLIPSE_PROCESSOR_COUNT)
 
 # Only set -j if we are under UNIX and if the make-tool used actually has "make" in the name
 # (we may also get here in the future e.g. for ninja)

Modules/CMakeFindKate.cmake

@@ -9,7 +9,7 @@
 # Try to find out how many CPUs we have and set the -j argument for make accordingly
 
 include(ProcessorCount)
-processorcount(_CMAKE_KATE_PROCESSOR_COUNT)
+ProcessorCount(_CMAKE_KATE_PROCESSOR_COUNT)
 
 # Only set -j if we are under UNIX and if the make-tool used actually has "make" in the name
 # (we may also get here in the future e.g. for ninja)

Modules/ProcessorCount.cmake

@@ -5,49 +5,56 @@
 ProcessorCount
 --------------
 
-ProcessorCount(var)
+This module provides the following function to determine the number of
+processors/cores:
 
-Determine the number of processors/cores and save value in ${var}
+.. command:: ProcessorCount
 
-Sets the variable named ${var} to the number of physical cores
-available on the machine if the information can be determined.
-Otherwise it is set to 0.  Currently this functionality is implemented
-for AIX, cygwin, FreeBSD, HPUX, Linux, macOS, QNX, Sun and
-Windows.
+  .. code-block:: cmake
 
-.. versionchanged:: 3.15
-  On Linux, returns the container CPU count instead of the host CPU count.
+    ProcessorCount(<variable>)
 
-This function is guaranteed to return a positive integer (>=1) if it
-succeeds.  It returns 0 if there's a problem determining the processor
-count.
+  Sets a local variable named ``<variable>`` to the number of logical CPU cores
+  available on the machine, if the information can be determined.  If
+  successful, the variable is guaranteed to be set to a positive integer (>=1).
+  If the processor count cannot be determined, it is set to 0.
 
-More generally accurate physical CPU count can be obtained via
-:command:`cmake_host_system_information`:
+  Currently, this functionality is implemented for AIX, Cygwin, FreeBSD, Haiku,
+  HPUX, Linux, macOS, QNX, Sun and Windows.
+
+  This function provides an approximation of the number of compute cores
+  available on the current machine, making it useful for parallel building and
+  testing.  It is meant to help utilize as much of the machine as seems
+  reasonable, though users should consider other workloads running on the
+  machine before using its full capacity for parallel tasks.
+
+  .. versionchanged:: 3.15
+    On Linux, returns the container CPU count instead of the host CPU count.
+
+.. note::
+
+  This module relies on system-dependent commands to determine the number of
+  processors, which may not always provide accurate information in certain
+  environments.  A more generally accurate logical CPU count can be also
+  obtained with the :command:`cmake_host_system_information`:
+
+  .. code-block:: cmake
+
+    cmake_host_system_information(RESULT n QUERY NUMBER_OF_LOGICAL_CORES)
+
+Examples
+^^^^^^^^
+
+Using ``ProcessorCount`` module in a :option:`ctest -S` dashboard script:
 
 .. code-block:: cmake
 
-  cmake_host_system_information(RESULT N
-                                QUERY NUMBER_OF_PHYSICAL_CORES)
-
-Example use, in a ctest -S dashboard script:
-
-.. code-block:: cmake
-
-   include(ProcessorCount)
-   ProcessorCount(N)
-   if(NOT N EQUAL 0)
-     set(CTEST_BUILD_FLAGS -j${N})
-     set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N})
-   endif()
-
-This function is intended to offer an approximation of the value of
-the number of compute cores available on the current machine, such
-that you may use that value for parallel building and parallel
-testing.  It is meant to help utilize as much of the machine as seems
-reasonable.  Of course, knowledge of what else might be running on the
-machine simultaneously should be used when deciding whether to request
-a machine's full capacity all for yourself.
+  include(ProcessorCount)
+  ProcessorCount(n)
+  if(NOT n EQUAL 0)
+    set(CTEST_BUILD_FLAGS -j${n})
+    set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${n})
+  endif()
 #]=======================================================================]
 
 # A more reliable way might be to compile a small C program that uses the CPUID