From e759bc8540593f0e2be0907722636c780230600a Mon Sep 17 00:00:00 2001
From: Florian Spreckelsen <f.spreckelsen@indiscale.com>
Date: Fri, 23 Aug 2024 13:35:26 +0200
Subject: [PATCH] DOC: Add callback example

---
 src/doc/converters.rst | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/src/doc/converters.rst b/src/doc/converters.rst
index d7feab82..f59e6d3d 100644
--- a/src/doc/converters.rst
+++ b/src/doc/converters.rst
@@ -362,12 +362,22 @@ exactly a Record as an argument and needs to return that Record after
 doing whatever custom treatment is needed. Additionally, it is given
 the ``RecordStore`` and the ``ValueStore`` in order to be able to
 access the records and values that have already been defined from
-within ``referenced_record_callback``. It is applied to all Records
-that are created from the dictionary and it can be used to, e.g.,
-transform values of some properties, or add special treatment to all
-Records of a specific type. ``referenced_record_callback`` is applied
-**after** the properties from the dictionary have been applied as
-explained above.
+within ``referenced_record_callback``. Such a function might look the
+following:
+
+.. code-block:: python
+
+   def my_callback(rec: db.Record, records: RecordStore, values: GeneralStore):
+       # do something with rec, possibly using other records or values from the stores...
+       rec.description = "This was updated in a callback"
+       return rec
+
+It is applied to all Records that are created from the dictionary and
+it can be used to, e.g., transform values of some properties, or add
+special treatment to all Records of a specific
+type. ``referenced_record_callback`` is applied **after** the
+properties from the dictionary have been applied as explained above.
+
 
 Further converters
 ++++++++++++++++++
-- 
GitLab