Improve documentation of GetPrerequisites.cmake

Put the function documentation into the header-comment, improve
formatting and list the user-relevant functions first.

Signed-off-by: Michael Wild <themiwi@users.sourceforge.net>

Modules/GetPrerequisites.cmake

@@ -1,14 +1,15 @@
-# GetPrerequisites.cmake
+# - This script provides functions to list the .dll, .dylib or .so files that
-#
+# an executable or shared library file depends on. (Its prerequisites.)
-# This script provides functions to list the .dll, .dylib or .so files that an
-# executable or shared library file depends on. (Its prerequisites.)
 #
 # It uses various tools to obtain the list of required shared library files:
 #   dumpbin (Windows)
 #   ldd (Linux/Unix)
 #   otool (Mac OSX)
 #
-# The following functions are provided by this script:
+# The following functions are provided by this module:
+#   get_prerequisites
+#   list_prerequisites
+#   list_prerequisites_by_glob
 #   gp_append_unique
 #   is_file_executable
 #   gp_item_default_embedded_path
@@ -18,12 +19,94 @@
 #   gp_resolved_file_type
 #     (projects can override with gp_resolved_file_type_override)
 #   gp_file_type
-#   get_prerequisites
-#   list_prerequisites
-#   list_prerequisites_by_glob
 #
 # Requires CMake 2.6 or greater because it uses function, break, return and
 # PARENT_SCOPE.
+#
+#  GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
+#                    <dirs>)
+# Get the list of shared library files required by <target>. The list in
+# the variable named <prerequisites_var> should be empty on first entry to
+# this function. On exit, <prerequisites_var> will contain the list of
+# required shared library files.
+#
+# <target> is the full path to an executable file. <prerequisites_var> is the
+# name of a CMake variable to contain the results. <exclude_system> must be 0
+# or 1 indicating whether to include or exclude "system" prerequisites. If
+# <recurse> is set to 1 all prerequisites will be found recursively, if set to
+# 0 only direct prerequisites are listed. <exepath> is the path to the top
+# level executable used for @executable_path replacment on the Mac. <dirs> is
+# a list of paths where libraries might be found: these paths are searched
+# first when a target without any path info is given. Then standard system
+# locations are also searched: PATH, Framework locations, /usr/lib...
+#
+#  LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]])
+# Print a message listing the prerequisites of <target>.
+#
+# <target> is the name of a shared library or executable target or the full
+# path to a shared library or executable file. If <recurse> is set to 1 all
+# prerequisites will be found recursively, if set to 0 only direct
+# prerequisites are listed. <exclude_system> must be 0 or 1 indicating whether
+# to include or exclude "system" prerequisites. With <verbose> set to 0 only
+# the full path names of the prerequisites are printed, set to 1 extra
+# informatin will be displayed.
+#
+#  LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>)
+# Print the prerequisites of shared library and executable files matching a
+# globbing pattern. <glob_arg> is GLOB or GLOB_RECURSE and <glob_exp> is a
+# globbing expression used with "file(GLOB" or "file(GLOB_RECURSE" to retrieve
+# a list of matching files. If a matching file is executable, its prerequisites
+# are listed.
+#
+# Any additional (optional) arguments provided are passed along as the
+# optional arguments to the list_prerequisites calls.
+#
+#  GP_APPEND_UNIQUE(<list_var> <value>)
+# Append <value> to the list variable <list_var> only if the value is not
+# already in the list.
+#
+#  IS_FILE_EXECUTABLE(<file> <result_var>)
+# Return 1 in <result_var> if <file> is a binary executable, 0 otherwise.
+#
+#  GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>)
+# Return the path that others should refer to the item by when the item
+# is embedded inside a bundle.
+#
+# Override on a per-project basis by providing a project-specific
+# gp_item_default_embedded_path_override function.
+#
+#  GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var>)
+# Resolve an item into an existing full path file.
+#
+# Override on a per-project basis by providing a project-specific
+# gp_resolve_item_override function.
+#
+#  GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var>)
+# Return the type of <file> with respect to <original_file>. String
+# describing type of prerequisite is returned in variable named <type_var>.
+#
+# Use <exepath> and <dirs> if necessary to resolve non-absolute <file>
+# values -- but only for non-embedded items.
+#
+# Possible types are:
+#   system
+#   local
+#   embedded
+#   other
+#
+# Override on a per-project basis by providing a project-specific
+# gp_resolved_file_type_override function.
+#
+#  GP_FILE_TYPE(<original_file> <file> <type_var>)
+# Return the type of <file> with respect to <original_file>. String
+# describing type of prerequisite is returned in variable named <type_var>.
+#
+# Possible types are:
+#   system
+#   local
+#   embedded
+#   other
+#
 
 #=============================================================================
 # Copyright 2008-2009 Kitware, Inc.
@@ -38,11 +121,6 @@
 # (To distributed this file outside of CMake, substitute the full
 #  License text for the above reference.)
 
-# gp_append_unique list_var value
-#
-# Append value to the list variable ${list_var} only if the value is not
-# already in the list.
-#
 function(gp_append_unique list_var value)
   set(contains 0)
 
@@ -59,12 +137,6 @@ function(gp_append_unique list_var value)
 endfunction(gp_append_unique)
 
 
-# is_file_executable file result_var
-#
-# Return 1 in ${result_var} if ${file} is a binary executable.
-#
-# Return 0 in ${result_var} otherwise.
-#
 function(is_file_executable file result_var)
   #
   # A file is not executable until proven otherwise:
@@ -132,14 +204,6 @@ function(is_file_executable file result_var)
 endfunction(is_file_executable)
 
 
-# gp_item_default_embedded_path item default_embedded_path_var
-#
-# Return the path that others should refer to the item by when the item
-# is embedded inside a bundle.
-#
-# Override on a per-project basis by providing a project-specific
-# gp_item_default_embedded_path_override function.
-#
 function(gp_item_default_embedded_path item default_embedded_path_var)
 
   # On Windows and Linux, "embed" prerequisites in the same directory
@@ -193,13 +257,6 @@ function(gp_item_default_embedded_path item default_embedded_path_var)
 endfunction(gp_item_default_embedded_path)
 
 
-# gp_resolve_item context item exepath dirs resolved_item_var
-#
-# Resolve an item into an existing full path file.
-#
-# Override on a per-project basis by providing a project-specific
-# gp_resolve_item_override function.
-#
 function(gp_resolve_item context item exepath dirs resolved_item_var)
   set(resolved 0)
   set(resolved_item "${item}")
@@ -332,23 +389,6 @@ warning: cannot resolve item '${item}'
 endfunction(gp_resolve_item)
 
 
-# gp_resolved_file_type original_file file exepath dirs type_var
-#
-# Return the type of ${file} with respect to ${original_file}. String
-# describing type of prerequisite is returned in variable named ${type_var}.
-#
-# Use ${exepath} and ${dirs} if necessary to resolve non-absolute ${file}
-# values -- but only for non-embedded items.
-#
-# Possible types are:
-#   system
-#   local
-#   embedded
-#   other
-#
-# Override on a per-project basis by providing a project-specific
-# gp_resolved_file_type_override function.
-#
 function(gp_resolved_file_type original_file file exepath dirs type_var)
   #message(STATUS "**")
 
@@ -445,17 +485,6 @@ function(gp_resolved_file_type original_file file exepath dirs type_var)
 endfunction()
 
 
-# gp_file_type original_file file type_var
-#
-# Return the type of ${file} with respect to ${original_file}. String
-# describing type of prerequisite is returned in variable named ${type_var}.
-#
-# Possible types are:
-#   system
-#   local
-#   embedded
-#   other
-#
 function(gp_file_type original_file file type_var)
   if(NOT IS_ABSOLUTE "${original_file}")
     message(STATUS "warning: gp_file_type expects absolute full path for first arg original_file")
@@ -470,30 +499,6 @@ function(gp_file_type original_file file type_var)
 endfunction(gp_file_type)
 
 
-# get_prerequisites target prerequisites_var exclude_system recurse dirs
-#
-# Get the list of shared library files required by ${target}. The list in
-# the variable named ${prerequisites_var} should be empty on first entry to
-# this function. On exit, ${prerequisites_var} will contain the list of
-# required shared library files.
-#
-#  target is the full path to an executable file
-#
-#  prerequisites_var is the name of a CMake variable to contain the results
-#
-#  exclude_system is 0 or 1: 0 to include "system" prerequisites , 1 to
-#   exclude them
-#
-#  recurse is 0 or 1: 0 for direct prerequisites only, 1 for all prerequisites
-#   recursively
-#
-#  exepath is the path to the top level executable used for @executable_path
-#   replacment on the Mac
-#
-#  dirs is a list of paths where libraries might be found: these paths are
-#   searched first when a target without any path info is given. Then standard
-#   system locations are also searched: PATH, Framework locations, /usr/lib...
-#
 function(get_prerequisites target prerequisites_var exclude_system recurse exepath dirs)
   set(verbose 0)
   set(eol_char "E")
@@ -706,19 +711,6 @@ function(get_prerequisites target prerequisites_var exclude_system recurse exepa
 endfunction(get_prerequisites)
 
 
-# list_prerequisites target all exclude_system verbose
-#
-#  ARGV0 (target) is the full path to an executable file
-#
-#  optional ARGV1 (all) is 0 or 1: 0 for direct prerequisites only,
-#   1 for all prerequisites recursively
-#
-#  optional ARGV2 (exclude_system) is 0 or 1: 0 to include "system"
-#   prerequisites , 1 to exclude them
-#
-#  optional ARGV3 (verbose) is 0 or 1: 0 to print only full path
-#   names of prerequisites, 1 to print extra information
-#
 function(list_prerequisites target)
   if("${ARGV1}" STREQUAL "")
     set(all 1)
@@ -771,17 +763,6 @@ function(list_prerequisites target)
 endfunction(list_prerequisites)
 
 
-# list_prerequisites_by_glob glob_arg glob_exp
-#
-#  glob_arg is GLOB or GLOB_RECURSE
-#
-#  glob_exp is a globbing expression used with "file(GLOB" to retrieve a list
-#   of matching files. If a matching file is executable, its prerequisites are
-#   listed.
-#
-# Any additional (optional) arguments provided are passed along as the
-# optional arguments to the list_prerequisites calls.
-#
 function(list_prerequisites_by_glob glob_arg glob_exp)
   message(STATUS "=============================================================================")
   message(STATUS "List prerequisites of executables matching ${glob_arg} '${glob_exp}'")