[CMake] Add some comments about how to use the file

CMakeLists.txt

@@ -5,6 +5,45 @@
 # NOTE: CMake support for Boost.Regex is currently experimental at best
 #       and the interface is likely to change in the future
 
+
+##### How-To:
+#
+# If you have a cmake project that wants to use and compile
+# boost_regex, as part of a single build system run, do the following:
+# 1) clone the boost project and all its sub-projects:
+#
+#   git clone --branch develop --depth 1 --recursive --shallow-submodules https://github.com/boostorg/boost.git boost-root
+#
+# 2) add to your cmake script:
+#
+#   add_subdirectory( <path-to-boost-root> [<build-dir-for-boost-libs>])
+#   target_link_libraries( <my-exec> PUBLIC Boost::regex)
+#
+# 3) run your cmake build as usual
+#
+# ## Explanation:
+#
+# Currently this file does not work standalone. It is expected to be
+# invoked from a parent script via add_subdirectory. That parent script
+# is responsible for providing targets for direct and indirect dependencies,
+# such as Boost::assert,  Boost::concept_check, e.g. by also adding those
+# libraries via add_submodule (order doesn't matter).
+# The parent script can be your own cmake script, but it is easier to just
+# use add the CMakeLists in the root of the boost super project, which
+# will in turn add all boost libraries usable with the add_subdirectory
+# Workflow.
+#
+# Note: You don't need to actually clone all boost libraries. E.g. look
+# into the travis ci file to see on which libraries boost_regex actually
+# depends or use boostdep https://github.com/boostorg/boostdep
+
+
+##### Current Limitations:
+#
+# - Doesn't compile or run tests
+# - Doesn't support installation
+#
+
 cmake_minimum_required( VERSION 3.5 )
 project( BoostRegex LANGUAGES CXX )
 
@@ -54,6 +93,8 @@ target_link_libraries( boost_regex
 )
 
 if( BOOST_REGEX_USE_ICU )
+    # ICU Targets could be provided by parent project,
+    # if not, look for them ourselves
     if( NOT TARGET ICU::dt )
         # components need to be listed explicitly
         find_package( ICU COMPONENTS dt in uc REQUIRED )