Can specify keyword arguments with a dict.kwargs

1 files changed, 39 insertions, 3 deletions

diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md
index 22b8be35e..9ea96c1d9 100644
--- a/docs/markdown/Syntax.md
+++ b/docs/markdown/Syntax.md
@@ -138,9 +138,9 @@ int main (int argc, char ** argv) {
 }'''
 ```
 
-These are raw strings that do not support the escape sequences listed above.
-These strings can also be combined with the string formatting functionality
-described below.
+These are raw strings that do not support the escape sequences listed
+above.  These strings can also be combined with the string formatting
+functionality described below.
 
 #### String formatting
 
@@ -351,6 +351,42 @@ creating build objects.
 executable('progname', 'prog.c')
 ```
 
+Most functions take only few positional arguments but several keyword
+arguments, which are specified like this:
+
+```meson
+executable('progname',
+  sources: 'prog.c',
+  c_args: '-DFOO=1')
+```
+
+Starting with version 0.49.0 keyword arguments can be specified
+dynamically. This is done by passing dictionary representing the
+keywords to set in the `kwargs` keyword. The previous example would be
+specified like this:
+
+```meson
+d = {'sources': 'prog.c',
+  'c_args': '-DFOO=1'}
+
+executable('progname',
+  kwargs: d)
+```
+
+A single function can take keyword argumets both directly in the
+function call and indirectly via the `kwargs` keyword argument. The
+only limitation is that it is a hard error to pass any particular key
+both as a direct and indirect argument.
+
+```meson
+d = {'c_args': '-DFOO'}
+executable('progname', 'prog.c',
+  c_args: '-DBAZ=1',
+  kwargs: d) # This is an error!
+```
+
+Attempting to do this causes Meson to immediately exit with an error.
+
 Method calls
 --