Update documentation of FindPythonInterp.cmake

Document new variables and update also comments in cmake code to explain
the current behaviour of FindPythonInterp.cmake module

Modules/FindPythonInterp.cmake

@@ -4,11 +4,17 @@
 #
 #  PYTHONINTERP_FOUND         - Was the Python executable found
 #  PYTHON_EXECUTABLE          - path to the Python interpreter
-#  Python_ADDITIONAL_VERSIONS - list of additional Python versions to search for
 #
+#  PYTHON_VERSION_STRING      - Python version found e.g. 2.5.2
+#  PYTHON_VERSION_MAJOR       - Python major version found e.g. 2
+#  PYTHON_VERSION_MINOR       - Python minor version found e.g. 5
+#  PYTHON_VERSION_PATCH       - Python patch version found e.g. 2
+#
+#  Python_ADDITIONAL_VERSIONS - list of additional Python versions to search for
 
 #=============================================================================
 # Copyright 2005-2010 Kitware, Inc.
+# Copyright 2011 Bjoern Ricks <[email protected]>
 #
 # Distributed under the OSI-approved BSD License (the "License");
 # see accompanying file Copyright.txt for details.
@@ -20,6 +26,7 @@
 # (To distribute this file outside of CMake, substitute the full
 #  License text for the above reference.)
 
+# Search for the current active python version first
 find_program(PYTHON_EXECUTABLE NAMES python)
 
 # Set up the versions we know about, in the order we will search. Always add
@@ -28,8 +35,7 @@ set(_Python_VERSIONS
   ${Python_ADDITIONAL_VERSIONS}
   2.7 2.6 2.5 2.4 2.3 2.2 2.1 2.0 1.6 1.5)
 
-# Run first with the Python version in the executable
-
+# Search for newest python version if python executable isn't found
 if(NOT PYTHON_EXECUTABLE)
     foreach(_CURRENT_VERSION ${_Python_VERSIONS})
       set(_Python_NAMES python${_CURRENT_VERSION})
@@ -43,6 +49,7 @@ if(NOT PYTHON_EXECUTABLE)
     endforeach()
 endif()
 
+# determine python version string
 if(PYTHON_EXECUTABLE)
     execute_process(COMMAND "${PYTHON_EXECUTABLE}" --version ERROR_VARIABLE _VERSION OUTPUT_QUIET ERROR_STRIP_TRAILING_WHITESPACE)
     string(REPLACE "Python " "" PYTHON_VERSION_STRING "${_VERSION}")