summary: Change 'section' to be a kwarg instead of positional

Fixes: #6372.

4 files changed, 39 insertions, 50 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 4868cdd..d8a8d11 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -1210,8 +1210,6 @@ This function prints its argument to stdout prefixed with WARNING:.
 ``` meson
     void summary(key, value)
     void summary(dictionary)
-    void summary(section_name, key, value)
-    void summary(section_name, dictionary)
 ```
 
 This function is used to summarize build configuration at the end of the build
@@ -1219,32 +1217,32 @@ process. This function provides a way for projects (and subprojects) to report
 this information in a clear way.
 
 The content is a serie of key/value pairs grouped into sections. If the section
-argument is omitted, those key/value pairs are implicitly grouped into a section
+keyword argument is omitted, those key/value pairs are implicitly grouped into a section
 with no title. key/value pairs can optionally be grouped into a dictionary,
-but keep in mind that dictionaries does not guarantee ordering.
-`section_name` and `key` must be strings, `value` can only be lists, integers,
-booleans or strings.
+but keep in mind that dictionaries does not guarantee ordering. `key` must be string,
+`value` can only be integer, boolean, string, or a list of those.
 
-`summary()` can be called multiple times as long as the same section_name/key
+`summary()` can be called multiple times as long as the same section/key
 pair doesn't appear twice. All sections will be collected and printed at
 the end of the configuration in the same order as they have been called.
 
 Keyword arguments:
 - `bool_yn` if set to true, all boolean values will be replaced by green YES
   or red NO.
+- `section` title to group a set of key/value pairs.
 
 Example:
 ```meson
 project('My Project', version : '1.0')
-summary('Directories', {'bindir': get_option('bindir'),
-                        'libdir': get_option('libdir'),
-                        'datadir': get_option('datadir'),
-                        })
-summary('Configuration', {'Some boolean': false,
-                          'Another boolean': true,
-                          'Some string': 'Hello World',
-                          'A list': ['string', 1, true],
-                          })
+summary({'bindir': get_option('bindir'),
+         'libdir': get_option('libdir'),
+         'datadir': get_option('datadir'),
+        }, section: 'Directories')
+summary({'Some boolean': false,
+         'Another boolean': true,
+         'Some string': 'Hello World',
+         'A list': ['string', 1, true],
+        }, section: 'Configuration')
 ```
 
 Output:
diff --git a/docs/markdown/snippets/summary.md b/docs/markdown/snippets/summary.md
index c5d64fd..91b3e5d 100644
--- a/docs/markdown/snippets/summary.md
+++ b/docs/markdown/snippets/summary.md
@@ -6,15 +6,15 @@ summarize build configuration at the end of the build process.
 Example:
 ```meson
 project('My Project', version : '1.0')
-summary('Directories', {'bindir': get_option('bindir'),
-                        'libdir': get_option('libdir'),
-                        'datadir': get_option('datadir'),
-                        })
-summary('Configuration', {'Some boolean': false,
-                          'Another boolean': true,
-                          'Some string': 'Hello World',
-                          'A list': ['string', 1, true],
-                          })
+summary({'bindir': get_option('bindir'),
+         'libdir': get_option('libdir'),
+         'datadir': get_option('datadir'),
+        }, section: 'Directories')
+summary({'Some boolean': false,
+         'Another boolean': true,
+         'Some string': 'Hello World',
+         'A list': ['string', 1, true],
+        }, section: 'Configuration')
 ```
 
 Output:
diff --git a/mesonbuild/interpreter.py b/mesonbuild/interpreter.py
index 1a9b5e6..14dfddd 100644
--- a/mesonbuild/interpreter.py
+++ b/mesonbuild/interpreter.py
@@ -2887,31 +2887,22 @@ external dependencies (including libraries) must go to "dependencies".''')
         mlog.log(mlog.bold('Message:'), argstr)
 
     @noArgsFlattening
-    @permittedKwargs({'bool_yn'})
+    @permittedKwargs({'section', 'bool_yn'})
     @FeatureNew('summary', '0.53.0')
     def func_summary(self, node, args, kwargs):
         if len(args) == 1:
             if not isinstance(args[0], dict):
-                raise InterpreterException('Argument 1 must be a dictionary.')
-            section = ''
+                raise InterpreterException('Summary first argument must be dictionary.')
             values = args[0]
         elif len(args) == 2:
             if not isinstance(args[0], str):
-                raise InterpreterException('Argument 1 must be a string.')
-            if isinstance(args[1], dict):
-                section, values = args
-            else:
-                section = ''
-                values = {args[0]: args[1]}
-        elif len(args) == 3:
-            if not isinstance(args[0], str):
-                raise InterpreterException('Argument 1 must be a string.')
-            if not isinstance(args[1], str):
-                raise InterpreterException('Argument 2 must be a string.')
-            section, key, value = args
-            values = {key: value}
+                raise InterpreterException('Summary first argument must be string.')
+            values = {args[0]: args[1]}
         else:
-            raise InterpreterException('Summary accepts at most 3 arguments.')
+            raise InterpreterException('Summary accepts at most 2 arguments.')
+        section = kwargs.get('section', '')
+        if not isinstance(section, str):
+            raise InterpreterException('Summary\'s section keyword argument must be string.')
         self.summary_impl(section, values, kwargs)
 
     def summary_impl(self, section, values, kwargs):
diff --git a/test cases/unit/74 summary/meson.build b/test cases/unit/74 summary/meson.build
index c689f96..c6d94d9 100644
--- a/test cases/unit/74 summary/meson.build
+++ b/test cases/unit/74 summary/meson.build
@@ -3,11 +3,11 @@ project('My Project', version : '1.0')
 subproject('sub')
 subproject('sub2', required : false)
 
-summary('Configuration', {'Some boolean': false,
-                          'Another boolean': true,
-                          'Some string': 'Hello World',
-                          'A list': ['string', 1, true],
-                          })
-summary('Configuration', 'A number', 1)
-summary('Configuration', 'yes', true, bool_yn : true)
-summary('Configuration', 'no', false, bool_yn : true)
+summary({'Some boolean': false,
+         'Another boolean': true,
+         'Some string': 'Hello World',
+         'A list': ['string', 1, true],
+        }, section: 'Configuration')
+summary('A number', 1, section: 'Configuration')
+summary('yes', true, bool_yn : true, section: 'Configuration')
+summary('no', false, bool_yn : true, section: 'Configuration')