From bcfbfbb343cc8ebe415fce042f5d0b1a1c488f69 Mon Sep 17 00:00:00 2001
From: Dylan Baker <dylan@pnwbakers.com>
Date: Tue, 5 Oct 2021 12:40:22 -0700
Subject: [PATCH] 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                | 14 ++++++++++++++
 docs/markdown/snippets/gnome_yelp_sources.md |  6 ++++++
 mesonbuild/modules/gnome.py                  |  8 +++++++-
 3 files changed, 27 insertions(+), 1 deletion(-)
 create mode 100644 docs/markdown/snippets/gnome_yelp_sources.md

diff --git a/docs/markdown/Gnome-module.md b/docs/markdown/Gnome-module.md
index 9477b292c..ccdb1f2b2 100644
--- a/docs/markdown/Gnome-module.md
+++ b/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`.
 
diff --git a/docs/markdown/snippets/gnome_yelp_sources.md b/docs/markdown/snippets/gnome_yelp_sources.md
new file mode 100644
index 000000000..3633d17ea
--- /dev/null
+++ b/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.
diff --git a/mesonbuild/modules/gnome.py b/mesonbuild/modules/gnome.py
index a6c0e1b2c..739faec76 100644
--- a/mesonbuild/modules/gnome.py
+++ b/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', []))