I found the function-level documentation baffling until i carefully read through the 'buildsystem' documentation, which lays out the fundamental model of how cmake works:

https://cmake.org/cmake/help/v3.12/manual/cmake-buildsystem....

Its not handholdingly simple, but it is precise and fairly complete, so you have a chance of understanding what is actually going on. All of the tutorials i've seen are just cookbooks with no explanation of how anything works, and mostly describe out-of-date or just plain bad approaches. The rash of "modern cmake" stuff avoids the latter, but really assumes you already know cmake. So that page of documentation was really crucial for me.

The 'language' documentation is also helpful:

https://cmake.org/cmake/help/v3.12/manual/cmake-language.7.h...

The only way I've been able to make any sense of CMake docs is in conjunction with examples -- searching on Github/enormous open source projects using it (e.g. LLVM). Just reading CMake docs to understand how to use directive x almost always leads to failure.

Yeah cmake docs suck. I dig the concept but figuring out how to use it is/was painful. I have not looked in a while.

It used to be the only chance you had to learn it was a book you could buy.

Oh no, you're not at all alone. I've actually used CMake as a "how not to do docs" antiexample in the past. More than once, actually.