From: Aki Tuomi <aki.tuomi@open-xchange.com>
Date: Fri, 30 Jan 2026 07:08:34 +0000 (+0200)
Subject: lib-var-expand: Add small description to header
X-Git-Tag: 2.4.3~52
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=628e30ff5b0ef9dfdfa21fca2866798df245cec7;p=thirdparty%2Fdovecot%2Fcore.git

lib-var-expand: Add small description to header
---

diff --git a/src/lib-var-expand/var-expand.h b/src/lib-var-expand/var-expand.h
index 58aea4ef03..189811fcfb 100644
--- a/src/lib-var-expand/var-expand.h
+++ b/src/lib-var-expand/var-expand.h
@@ -1,6 +1,26 @@
 #ifndef VAR_EXPAND_NEW_H
 #define VAR_EXPAND_NEW_H
 
+/** Variable expansion programs **
+
+  A variable expansion program is a set of filters delineated with %{},
+  or a literal-only program which expands to the string it contains.
+  See https://doc.dovecot.org/latest/core/settings/syntax.html#variable-expansion.
+
+  The normal usage is to call t_var_expand() to get rendition of a program from
+  data stack memory, or var_expand() if you want to provide the string yourself.
+  The string is appended to, or truncated to where it was on starting on failure.
+
+  If you need to expand the program multiple times, you should use
+  var_expand_program_create() to create a reusable program chain and then call
+  var_expand_program_execute() to expand it. Since parameters are given to execute
+  you can get the same program executed with different parameters, so you don't
+  have to rebuild the program if your variables are changed.
+
+  The function var_expand_program_create() parses a string that can contain
+  one or more programs, and chains them together. This is usually what is wanted.
+*/
+
 /* Used for getting either prefix:key values, or dynamic values for keys
    in value tables.