1 files changed, 24 insertions, 7 deletions
diff --git a/docs/markdown/snippets/qt_preprocessed_varargs_deprecated.md b/docs/markdown/snippets/qt_preprocessed_varargs_deprecated.md
index f76369532..5418eb3aa 100644
--- a/docs/markdown/snippets/qt_preprocessed_varargs_deprecated.md
+++ b/docs/markdown/snippets/qt_preprocessed_varargs_deprecated.md
@@ -1,16 +1,33 @@
-## Qt.preprocess positional source arguments deprecated
+## Qt.preprocess source arguments deprecated
 
 The `qt.preprocess` method currently has this signature:
 `qt.preprocess(name: str | None, *srcs: str)`, this is not a nice signature
-because it's confusing, and there's a `sources` keyword argument that does
-exactly the same thing. Instead of
+because it's confusing, and there's a `sources` keyword argument as well.
+Both of these pass sources through unmodified, this is a bit of a historical
+accident, and not the way that any other module works. These have been
+deprecated, so instead of:
 ```meson
-qt.preprocess(name, list, of, sources)
+sources = qt.preprocess(
+    name,
+    list, of, sources,
+    sources : [more, sources],
+    ... # things to process,
+)
+
+executable(
+    'foo',
+    sources,
+)
 ```
 use
 ```meson
-qt.preprocess(
+processed = qt.preprocess(
     name,
-    sources : [list,  of , sources],
+    ... # thins to process
 )
-```
-\ No newline at end of file
+
+executable(
+    'foo',
+    'list', 'of', 'sources', 'more', 'sources', processed,
+)
+```