From 947438a2cf394eb9b289da5f712533f1d385f3d1 Mon Sep 17 00:00:00 2001
From: Hagen Wierstorf <hwierstorf@audeering.com>
Date: Wed, 25 Oct 2023 13:26:58 +0200
Subject: [PATCH] Expand docstring

---
 audformat/core/utils.py    | 16 +++++++++++-----
 tests/test_utils_concat.py |  8 ++++++++
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/audformat/core/utils.py b/audformat/core/utils.py
index 715f95ee..868ff1fa 100644
--- a/audformat/core/utils.py
+++ b/audformat/core/utils.py
@@ -69,15 +69,21 @@ def concat(
     a custom aggregation function can be provided
     with ``aggregate_function``
     that converts the overlapping values
-    into a single one.
+    into a single value.
 
     Args:
         objs: objects
         overwrite: overwrite values where indices overlap
-        aggregate_function: function to be applied on all entries
-            that contain more then one data point per index.
-            The function gets a dataframe row as input,
-            and is expected to return a single value
+        aggregate_function: function to aggregate values
+            for all entries
+            that contain more than one value per index.
+            The function gets a dataframe row as input.
+            E.g. set to
+            :func:`numpy.mean`
+            to average the values
+            or to
+            ``lambda row: tuple(row.to_list())``
+            to return all values as a tuple
 
     Returns:
         concatenated objects
diff --git a/tests/test_utils_concat.py b/tests/test_utils_concat.py
index 6900abee..1c370729 100644
--- a/tests/test_utils_concat.py
+++ b/tests/test_utils_concat.py
@@ -579,6 +579,14 @@ def test_concat(objs, overwrite, expected):
             np.mean,
             pd.Series([1, 2], pd.Index(['a', 'b']), dtype='float'),
         ),
+        (
+            [
+                pd.Series([1, 2], pd.Index(['a', 'b']), dtype='float'),
+                pd.Series([1, 2], pd.Index(['a', 'b']), dtype='float'),
+            ],
+            lambda x: tuple(x.to_list()),
+            pd.Series([(1, 1), (2, 2)], pd.Index(['a', 'b']), dtype='object'),
+        ),
         (
             [
                 pd.Series([1, 2], pd.Index(['a', 'b']), dtype='float'),