add FIXME and TODO comments to compile_cmake.dox

doc/src/tutorial/compile_cmake.dox

@@ -5,7 +5,15 @@
 
 CMake can be used to generate Visual Studio solutions on Windows, Makefiles (on Linux and OS X) and build metadata for other build systems for PortAudio. You should obtain a recent version of CMake from [http://www.cmake.org] if you do not have one already. If you are unfamiliar with CMake, this section will provide some information on using CMake to build PortAudio.
 
-On Linux, CMake serves a very similar purpose to an autotools "configure" script - except it can generate build metadata apart from Makefiles. The equivalent of the following on POSIX'y systems:
+Warning: PortAudio's CMake support has significantly changed since the PortAudio 19.7 release and is currently in flux. The documentation below is not up to date. Proceed with care. Known issues are marked with "FIXME" or "TODO", the list of open CMake related build issues is here: [https://github.com/PortAudio/portaudio/issues?q=is%3Aissue+is%3Aopen+label%3Abuild-cmake]
+
+FIXME: fix these docs and then remove the above warning.
+
+@section cmake_posix Building on Unix-like Systems
+
+TODO: check whether these unix instructions are still valid
+
+On Unix-like systems such as Linux and macOS, CMake serves a very similar purpose to an autotools "configure" script - except it can generate build metadata apart from Makefiles. The equivalent of the following on POSIX'y systems:
 
     build_path> {portaudio path}/configure --prefix=/install_location
     build_path> make
@@ -23,6 +31,12 @@ The "-G" option specifies the type of build metadata which will be generated. Yo
 
 "make install" should install the same set of files that are installed using the usual configure script included with PortAudio along with a few extra files (similar to pkg-config metadata files) which make it easier for other CMake projects to use the installed libraries.
 
+FIXME: do these instructions still work? do they install static **and** dynamic libraries as with PortAudio V19.7? According to #468 this is currently not the case.
+
+@section cmake_windows Building on Windows
+
+TODO: check whether these windows instructions are still valid
+
 On Windows, you can use CMake to generate Visual Studio project files which can be used to create the PortAudio libraries. The following serves as an example (and should be done from a directory outside the PortAudio tree) which will create Visual Studio 2015 project files targeting a 64-bit build:
 
     C:\PABUILD> cmake {portaudio path} -G "Visual Studio 14 2015 Win64"
@@ -31,15 +45,27 @@ After executing the above, you can either open the generated solution with Visua
 
     C:\PABUILD> cmake --build . --config Release
 
+FIXME: describe how to select between static and dynamic build outputs, and note that this is a change since V19.7 (see #468)
+
+Note: in recent versions of Visual Studio you can directly open the cmake file as an alternative to using a Visual Studio project file.
+
+@subsection cmake_windows_asio Building with ASIO Support
+
 If you want ASIO support you need to obtain the ASIO2 SDK from Steinberg and place it according to \ref compile_windows_asio_msvc. Both ASIO and the DirectX SDK are automatically searched for by the CMake script - if they are found, they will be enabled by default.
 
+FIXME: recent cmake changes can automatically download the ASIO2 SDK, so the instructions need to be clear about how to use a local or auto-downloaded ASIO SDK (see #518).
+
 @section cmake_using Using PortAudio in your CMake project
 
+FIXME: this section is currently incorrect (see ticket #486) It's not clear whether the cmakelists or documentation should be updated.
+
 PortAudio defines the following CMake targets:
 
  - "portaudio_static" for a static library and
  - "portaudio" for a dynamic library
 
+ FIXME: describe how to select between static and dynamic build artifacts or revert to old behavior (see #486)
+
 If you installed PortAudio as described above in \ref cmake_building and the install prefix you used (CMAKE_INSTALL_PREFIX) is in your system PATH or CMAKE_MODULE_PATH CMake variable, you should be able to use:
 
     find_package(portaudio)