modules/gnome: deprecate yelp variadic sources

Yelp currently can take sources two different ways, the first is via
variadic arguments, the second is by a keyword argument. If the keyword
is passed then the variadic arguments are silently ignored, which is
obviously not ideal. Fortunately the variadic form was never documented,
and is likely not in wide use.

This patch fixes it by deprecating the variadic form, and warning if
both are passed. It does not change behavior as someone may be relying
on it.

docs/markdown/Gnome-module.md

@@ -298,9 +298,23 @@ VAPI or Vala binaries.
 
 ### gnome.yelp()
 
+```meson
+  gnome.yelp(id: string, sources: ...string, sources: []string, media: []string,
+             languages: []string, symlink_media: bool = true): void
+```
+
 Installs help documentation using Yelp. The first argument is the
 project id.
 
+Additionally, sources can be passed as additional positional arguments. This
+was, however, undocumented and never officially supported. Due to a longstanding
+bug, passing sources as a keyword argument will result in the positional
+argument sources to be ignored. *since 0.60.0* A warning is raised in this case.
+
+*Since 0.60.0* the use of the positional argument sources has been deprecated,
+and the "sources" keyword argument should be used instead. The passing of
+sources as positional arguments will be removed in the future.
+
 This also creates two targets for translations
 `help-$project-update-po` and `help-$project-pot`.
 

docs/markdown/snippets/gnome_yelp_sources.md

@@ -0,0 +1,6 @@
+## gnome.yelp variadic argument deprecation
+
+`gnome.yelp` previously allowed sources to be passed either as variadic
+arguments or as a keyword argument. If the keyword argument was given the
+variadic arguments would be silently ignored. This has changed in 0.60.0, the
+variadic form has been deprecated, and a warning is printed if both are given.

mesonbuild/modules/gnome.py

@@ -33,7 +33,7 @@ from ..mesonlib import (
     join_args, HoldableObject
 )
 from ..dependencies import Dependency, PkgConfigDependency, InternalDependency
-from ..interpreterbase import noPosargs, noKwargs, permittedKwargs, FeatureNew, FeatureNewKwargs, FeatureDeprecatedKwargs
+from ..interpreterbase import noPosargs, noKwargs, permittedKwargs, FeatureNew, FeatureNewKwargs, FeatureDeprecatedKwargs, FeatureDeprecated
 from ..interpreterbase import typed_kwargs, KwargInfo, ContainerTypeInfo
 from ..programs import ExternalProgram, OverrideProgram
 from ..build import CustomTarget, CustomTargetIndex, GeneratedList
@@ -969,12 +969,18 @@ class GnomeModule(ExtensionModule):
             raise MesonException('Yelp requires a project id')
 
         project_id = args[0]
+        if len(args) > 1:
+            FeatureDeprecated.single_use('gnome.yelp more than one positional argument', '0.60.0', 'use the "sources" keyword argument instead.')
+
         sources = mesonlib.stringlistify(kwargs.pop('sources', []))
         if not sources:
             if len(args) > 1:
                 sources = mesonlib.stringlistify(args[1:])
             if not sources:
                 raise MesonException('Yelp requires a list of sources')
+        else:
+            if len(args) > 1:
+                mlog.warning('"gnome.yelp" ignores positional sources arguments when the "sources" keyword argument is set')
         source_str = '@@'.join(sources)
 
         langs = mesonlib.stringlistify(kwargs.pop('languages', []))