From 3423020a687322aaf29528c382736e349be69cb3 Mon Sep 17 00:00:00 2001
From: Sophist <3001893+Sophist-UK@users.noreply.github.com>
Date: Tue, 19 Jan 2021 16:38:54 +0000
Subject: [PATCH 1/3] Consistent description, more examples.

---
 picard/script/functions.py | 46 ++++++++++++++++++++++++++------------
 1 file changed, 32 insertions(+), 14 deletions(-)

diff --git a/picard/script/functions.py b/picard/script/functions.py
index bf81b7271..754959d0d 100644
--- a/picard/script/functions.py
+++ b/picard/script/functions.py
@@ -191,7 +191,7 @@ def func_if(parser, _if, _then, _else=None):
 
 
 @script_function(eval_args=False, documentation=N_(
-    """`$if2(a1,a2,a3,...)`
+    """`$if2(a1,a2,a3...)`
 
 Returns first non empty argument."""
 ))
@@ -492,7 +492,7 @@ def func_trim(parser, text, char=None):
 
 
 @script_function(documentation=N_(
-    """`$add(x,y,*args)`
+    """`$add(x,y...)`
 
 Add `y` to `x`.
 Can be used with an arbitrary number of arguments.
@@ -510,7 +510,7 @@ def func_add(parser, x, y, *args):
 
 
 @script_function(documentation=N_(
-    """`$sub(x,y,*args)`
+    """`$sub(x,y...)`
 
 Subtracts `y` from `x`.
 Can be used with an arbitrary number of arguments.
@@ -528,7 +528,7 @@ def func_sub(parser, x, y, *args):
 
 
 @script_function(documentation=N_(
-    """`$div(x,y,*args)`
+    """`$div(x,y...)`
 
 Divides `x` by `y`.
 Can be used with an arbitrary number of arguments.
@@ -548,7 +548,7 @@ def func_div(parser, x, y, *args):
 
 
 @script_function(documentation=N_(
-    """`$mod(x,y,*args)`
+    """`$mod(x,y...)`
 
 Returns the remainder of `x` divided by `y`.
 Can be used with an arbitrary number of arguments.
@@ -566,7 +566,7 @@ def func_mod(parser, x, y, *args):
 
 
 @script_function(documentation=N_(
-    """`$mul(x,y,*args)`
+    """`$mul(x,y...)`
 
 Multiplies `x` by `y`.
 Can be used with an arbitrary number of arguments.
@@ -584,7 +584,7 @@ def func_mul(parser, x, y, *args):
 
 
 @script_function(documentation=N_(
-    """`$or(x,y,*args)`
+    """`$or(x,y...)`
 
 Returns true if either `x` or `y` not empty.
     Can be used with an arbitrary number of arguments.
@@ -598,7 +598,7 @@ def func_or(parser, x, y, *args):
 
 
 @script_function(documentation=N_(
-    """`$and(x,y,*args)`
+    """`$and(x,y...)`
 
 Returns true if both `x` and `y` are not empty.
     Can be used with an arbitrary number of arguments.
@@ -870,14 +870,14 @@ def func_truncate(parser, text, length):
 
 
 @script_function(check_argcount=False, documentation=N_(
-    """`$swapprefix(text,*prefixes="a","the")`
+    """`$swapprefix(text,prefix...)`
 
 Moves the specified `prefixes` from the beginning to the end of `text`.
 If no prefix is specified 'A' and 'The' are used by default.
 
 Example:
 
-    $swapprefix(%albumartist%,A,An,The,Le)
+    $swapprefix(%albumartist%,A,An,The,La,Le,Les,Un,Une)
 
 _Since Picard 1.3, previously as a plugin since Picard 0.13_"""
 ))
@@ -891,11 +891,15 @@ def func_swapprefix(parser, text, *prefixes):
 
 
 @script_function(check_argcount=False, documentation=N_(
-    """`$delprefix(text,*prefixes="a","the")`
+    """`$delprefix(text,prefix...)`
 
 Deletes the specified `prefixes` from the beginning of `text`.
 If no prefix is specified 'A' and 'The' are used by default.
 
+Example:
+
+    $delprefix(%albumartist%,A,An,The,La,Le,Les,Un,Une)
+
 _Since Picard 1.3_"""
 ))
 def func_delprefix(parser, text, *prefixes):
@@ -1164,7 +1168,11 @@ Iterates over each element found in the multi-value tag `name` and updates the
     value of the element to the value returned by `code`, returning the updated
     multi-value tag. For each loop, the element value is first stored in the tag
     `_loop_value` and the count is stored in the tag `_loop_count`. This allows
-    the element or count value to be accessed within the `code` script."""
+    the element or count value to be accessed within the `code` script.
+
+Example:
+    $map(First:A; Second:B,$upper(%_loop_count%=%_loop_value%)) results in "1=FIRST:A; 2=SECOND:B"
+"""
 ))
 def func_map(parser, multi, loop_code, separator=MULTI_VALUED_JOINER):
     multi_value = MultiValue(parser, multi, separator)
@@ -1252,7 +1260,12 @@ def func_datetime(parser, format=None):
 @script_function(eval_args=False, documentation=N_(
     """`$sortmulti(name,separator="; ")`
 
-Returns a copy of the multi-value tag `name` with the elements sorted in ascending order."""
+Returns a copy of the multi-value tag `name` with the elements sorted in ascending order.
+
+Example:
+
+    $sortmulti(B; A; C) results in "A; B; C"
+"""
 ))
 def func_sortmulti(parser, multi, separator=MULTI_VALUED_JOINER):
     multi_value = MultiValue(parser, multi, separator)
@@ -1264,7 +1277,12 @@ def func_sortmulti(parser, multi, separator=MULTI_VALUED_JOINER):
 
 Returns a copy of the multi-value tag `name` with the elements in reverse order.
     This can be used in conjunction with the `$sortmulti` function to sort in
-    descending order."""
+    descending order.
+
+Example:
+
+    $reversemulti($sortmulti(B; A; C)) results in "C; B; A"
+"""
 ))
 def func_reversemulti(parser, multi, separator=MULTI_VALUED_JOINER):
     multi_value = MultiValue(parser, multi, separator)

From 8d7c40c1b9f6657b1178e4cef5896c7e3cedbff5 Mon Sep 17 00:00:00 2001
From: Philipp Wolfer <ph.wolfer@gmail.com>
Date: Sun, 28 Feb 2021 17:14:22 +0100
Subject: [PATCH 2/3] PICARD-2105: Use trailing commas for variable parameters

---
 picard/script/functions.py | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/picard/script/functions.py b/picard/script/functions.py
index 754959d0d..bbade36f1 100644
--- a/picard/script/functions.py
+++ b/picard/script/functions.py
@@ -191,7 +191,7 @@ def func_if(parser, _if, _then, _else=None):
 
 
 @script_function(eval_args=False, documentation=N_(
-    """`$if2(a1,a2,a3...)`
+    """`$if2(a1,a2,a3,...)`
 
 Returns first non empty argument."""
 ))
@@ -492,7 +492,7 @@ def func_trim(parser, text, char=None):
 
 
 @script_function(documentation=N_(
-    """`$add(x,y...)`
+    """`$add(x,y,...)`
 
 Add `y` to `x`.
 Can be used with an arbitrary number of arguments.
@@ -510,7 +510,7 @@ def func_add(parser, x, y, *args):
 
 
 @script_function(documentation=N_(
-    """`$sub(x,y...)`
+    """`$sub(x,y,...)`
 
 Subtracts `y` from `x`.
 Can be used with an arbitrary number of arguments.
@@ -528,7 +528,7 @@ def func_sub(parser, x, y, *args):
 
 
 @script_function(documentation=N_(
-    """`$div(x,y...)`
+    """`$div(x,y,...)`
 
 Divides `x` by `y`.
 Can be used with an arbitrary number of arguments.
@@ -548,7 +548,7 @@ def func_div(parser, x, y, *args):
 
 
 @script_function(documentation=N_(
-    """`$mod(x,y...)`
+    """`$mod(x,y,...)`
 
 Returns the remainder of `x` divided by `y`.
 Can be used with an arbitrary number of arguments.
@@ -566,7 +566,7 @@ def func_mod(parser, x, y, *args):
 
 
 @script_function(documentation=N_(
-    """`$mul(x,y...)`
+    """`$mul(x,y,...)`
 
 Multiplies `x` by `y`.
 Can be used with an arbitrary number of arguments.
@@ -584,7 +584,7 @@ def func_mul(parser, x, y, *args):
 
 
 @script_function(documentation=N_(
-    """`$or(x,y...)`
+    """`$or(x,y,...)`
 
 Returns true if either `x` or `y` not empty.
     Can be used with an arbitrary number of arguments.
@@ -598,7 +598,7 @@ def func_or(parser, x, y, *args):
 
 
 @script_function(documentation=N_(
-    """`$and(x,y...)`
+    """`$and(x,y,...)`
 
 Returns true if both `x` and `y` are not empty.
     Can be used with an arbitrary number of arguments.
@@ -870,7 +870,7 @@ def func_truncate(parser, text, length):
 
 
 @script_function(check_argcount=False, documentation=N_(
-    """`$swapprefix(text,prefix...)`
+    """`$swapprefix(text,prefix,...)`
 
 Moves the specified `prefixes` from the beginning to the end of `text`.
 If no prefix is specified 'A' and 'The' are used by default.
@@ -891,7 +891,7 @@ def func_swapprefix(parser, text, *prefixes):
 
 
 @script_function(check_argcount=False, documentation=N_(
-    """`$delprefix(text,prefix...)`
+    """`$delprefix(text,prefix,...)`
 
 Deletes the specified `prefixes` from the beginning of `text`.
 If no prefix is specified 'A' and 'The' are used by default.
@@ -928,10 +928,10 @@ def _delete_prefix(parser, text, *prefixes):
 
 
 @script_function(check_argcount=False, documentation=N_(
-    """`$eq_any(x,a1,a2...)`
+    """`$eq_any(x,a1,a2,...)`
 
 Returns true if `x` equals `a1` or `a2` or ...
-Functionally equivalent to `$or($eq(x,a1),$eq(x,a2) ...)`.
+Functionally equivalent to `$or($eq(x,a1),$eq(x,a2),...)`.
 Functionally equivalent to the eq2 plugin."""
 ))
 def func_eq_any(parser, x, *args):
@@ -940,10 +940,10 @@ def func_eq_any(parser, x, *args):
 
 
 @script_function(check_argcount=False, documentation=N_(
-    """`$ne_all(x,a1,a2...)`
+    """`$ne_all(x,a1,a2,...)`
 
 Returns true if `x` does not equal `a1` and `a2` and ...
-Functionally equivalent to `$and($ne(x,a1),$ne(x,a2) ...)`.
+Functionally equivalent to `$and($ne(x,a1),$ne(x,a2),...)`.
 Functionally equivalent to the ne2 plugin."""
 ))
 def func_ne_all(parser, x, *args):
@@ -952,10 +952,10 @@ def func_ne_all(parser, x, *args):
 
 
 @script_function(check_argcount=False, documentation=N_(
-    """`$eq_all(x,a1,a2...)`
+    """`$eq_all(x,a1,a2,...)`
 
 Returns true if `x` equals `a1` and `a2` and ...
-Functionally equivalent to `$and($eq(x,a1),$eq(x,a2) ...)`.
+Functionally equivalent to `$and($eq(x,a1),$eq(x,a2),...)`.
 
 Example:
 
@@ -970,10 +970,10 @@ def func_eq_all(parser, x, *args):
 
 
 @script_function(check_argcount=False, documentation=N_(
-    """`$ne_any(x,a1,a2...)`
+    """`$ne_any(x,a1,a2,...)`
 
 Returns true if `x` does not equal `a1` or `a2` or ...
-Functionally equivalent to `$or($ne(x,a1),$ne(x,a2) ...)`.
+Functionally equivalent to `$or($ne(x,a1),$ne(x,a2),...)`.
 
 Example:
 

From d41be0f94d54d1b64eb5431de0e0a874d0071200 Mon Sep 17 00:00:00 2001
From: Philipp Wolfer <ph.wolfer@gmail.com>
Date: Sun, 28 Feb 2021 17:14:53 +0100
Subject: [PATCH 3/3] PICARD-2105: Clarify docs for $swapprefix and $delprefix

---
 picard/script/functions.py | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/picard/script/functions.py b/picard/script/functions.py
index bbade36f1..0506f8e41 100644
--- a/picard/script/functions.py
+++ b/picard/script/functions.py
@@ -870,10 +870,11 @@ def func_truncate(parser, text, length):
 
 
 @script_function(check_argcount=False, documentation=N_(
-    """`$swapprefix(text,prefix,...)`
+    """`$swapprefix(text,prefix1,prefix2,...)`
 
-Moves the specified `prefixes` from the beginning to the end of `text`.
-If no prefix is specified 'A' and 'The' are used by default.
+Moves the specified prefixes from the beginning to the end of `text`. Multiple
+prefixes can be specified as separate parameters. If no prefix is specified 'A'
+and 'The' are used by default.
 
 Example:
 
@@ -891,10 +892,11 @@ def func_swapprefix(parser, text, *prefixes):
 
 
 @script_function(check_argcount=False, documentation=N_(
-    """`$delprefix(text,prefix,...)`
+    """`$delprefix(text,prefix1,prefix2,...)`
 
-Deletes the specified `prefixes` from the beginning of `text`.
-If no prefix is specified 'A' and 'The' are used by default.
+Deletes the specified prefixes`from the beginning of `text`. Multiple
+prefixes can be specified as separate parameters.  If no prefix is specified 'A'
+and 'The' are used by default.
 
 Example: