header comment in AssertLibraryFunction.cmake

pub/cmake/modules/AssertLibraryFunction.cmake

@@ -2,7 +2,8 @@
 # AssertLibraryFunction
 # ---------------------
 #
-# Assert that library contains function, or raise fatal error.
+# ASSERT_LIBRARY_FUNCTION checks whether given libraries contain
+# a given function. If this is not the case, a fatal error is raised.
 #
 # CHECK_LIBRARY_EXISTS (LIBNAME FUNCTION LOCATION)
 #
@@ -10,7 +11,7 @@
 #
 #   LIBNAME  - library name (case sensitive)
 #   FUNCTION - name of the function to be searched in ${LIBNAME}_LIBRARIES
-#   LOCATION - location where the library should be found
+#   LOCATION - where the library should be found (if unsure, use "")
 #
 #
 # The following variables may be set before calling this macro to modify
@@ -22,6 +23,32 @@
 #   CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
 #   CMAKE_REQUIRED_LIBRARIES = list of libraries to link
 #   CMAKE_REQUIRED_QUIET = execute quietly without messages
+#
+# This function is meant to be used in Find<Package>.cmake modules,
+# which in turn should be called through
+#
+# ::
+#   find_package(<Package> [QUIET] [REQUIRED])
+#
+# Within a Find<Package>.cmake module, find_package_handle_standard_args
+# must be called before any call of ASSERT_LIBRARY_FUNCTION.
+# Typically, Find<Package>.cmake looks like the following:
+#
+# ::
+# 
+#   find_path(<Package>_INCLUDE_DIR <include_file>)
+#   find_library(<Package>_LIBRARIES NAMES <library_name> <Package>)
+#   
+#   include(FindPackageHandleStandardArgs)
+#   find_package_handle_standard_args(<Package> DEFAULT_MSG <Package>_LIBRARIES <Package>_INCLUDE_DIR)
+#   
+#   include(AssertLibraryFunction)
+#   assert_library_function(<Package> <function_name> "")
+#   
+#   mark_as_advanced(<Package>_INCLUDE_DIR <Package>_LIBRARIES)
+#   
+# The result of ASSERT_LIBRARY_FUNCTION is cached in a variable named
+# ${LIBNAME}_${FUNCTION}.
 
 #=============================================================================
 # Based on CheckLibrariesExists (Copyright 2002-2009 Kitware, Inc.)