From fdfe14b345cc405952b5c150a0e52cb4ddc45e2b Mon Sep 17 00:00:00 2001
From: Valentin Kaisermayer
 <50108075+ValentinKaisermayer@users.noreply.github.com>
Date: Mon, 6 May 2024 08:03:57 +0200
Subject: [PATCH] Improves doc on collapse (#526)

* improves doc on collapse

* adds docs
---
 docs/src/combine.md |  4 ++++
 src/combine.jl      | 23 +++++++++++++++++++++--
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/docs/src/combine.md b/docs/src/combine.md
index e6a3eef4..1edde22a 100644
--- a/docs/src/combine.md
+++ b/docs/src/combine.md
@@ -97,6 +97,10 @@ using Statistics
 collapse(cl, month, last, mean)
 ```
 
+```@docs
+collapse
+```
+
 ## `vcat`
 
 The `vcat` method is used to concatenate time series: if you have two
diff --git a/src/combine.jl b/src/combine.jl
index 6cb3db6f..b4fabaf0 100644
--- a/src/combine.jl
+++ b/src/combine.jl
@@ -159,8 +159,27 @@ function collapse(ta::TimeArray, period::Function, timestamp::Function,
     TimeArray(ts′, val′, colnames(ta), meta(ta))
 end
 
-collapse(ta::TimeArray, p::Period, t::Function, v::Function = t; kw...) =
-    collapse(ta, x -> floor(x, p), t, v; kw...)
+"""
+    $(SIGNATURES)
+
+The `collapse` method allows for compressing data into a larger time frame. 
+
+For example, converting daily data into monthly data. When compressing dates, something rational has to be done with the values
+that lived in the more granular time frame. To define what happens, a function call is made.
+
+## Arguments:
+- `ta::TimeArray`: Original data
+- `period::Union{Function,Dates.Period}`: Period or method for determining the period
+- `timestamp::Function`: Method that determines which timestamp represents the whole period, e.g. `last`
+- `value::Function = timestamp`: Method that should be applied to the data within the period, e.g. `mean`
+
+```julia
+collapse(ta, month, last)
+collapse(ta, month, last, mean)
+```
+"""
+collapse(ta::TimeArray, period::Period, timestamp::Function, value::Function = timestamp; kw...) =
+    collapse(ta, x -> floor(x, period), timestamp, value; kw...)
 
 # vcat ######################