Docs: Mention important macOS caveat about function detection [ci skip]

1 files changed, 18 insertions, 3 deletions

diff --git a/docs/markdown/Compiler-properties.md b/docs/markdown/Compiler-properties.md
index 579417a..1228f42 100644
--- a/docs/markdown/Compiler-properties.md
+++ b/docs/markdown/Compiler-properties.md
@@ -160,15 +160,30 @@ Does a function exist?
 
 Just having a header doesn't say anything about its
 contents. Sometimes you need to explicitly check if some function
-exists. This is how we would check whether the function `somefunc`
-exists in header `someheader.h`
+exists. This is how we would check whether the function `open_memstream`
+exists in header `stdio.h`
 
 ```meson
-if compiler.has_function('somefunc', prefix : '#include<someheader.h>')
+if compiler.has_function('open_memstream', prefix : '#include <stdio.h>')
   # function exists, do whatever is required.
 endif
 ```
 
+Note that, on macOS programs can be compiled targeting older macOS
+versions than the one that the program is compiled on. It can't be
+assumed that the OS version that is compiled on matches the OS
+version that the binary will run on.
+
+Therefore when detecting function availability with `has_function`, it
+is important to specify the correct header in the prefix argument.
+
+In the example above, the function `open_memstream` is detected, which
+was introduced in macOS 10.13. When the user builds on macOS 10.13, but
+targeting macOS 10.11 (`-mmacosx-version-min=10.11`), this will correctly
+report the function as missing. Without the header however, it would lack
+the necessary availability information and incorrectly report the function
+as available.
+
 Does a structure contain a member?
 ==