From 3732f9bd070bd98f64185c0b361fd15a53b91c85 Mon Sep 17 00:00:00 2001
From: Nirbheek Chauhan <nirbheek@centricular.com>
Date: Tue, 25 Feb 2020 03:14:50 +0530
Subject: [PATCH] docs: Document generated headers caveats for genmarshal

And also link to the Meson FAQ that explains why this is needed so
people aren't just cargo-culting code.
---
 docs/reference/gobject/glib-genmarshal.xml | 18 +++++++++++++++++-
 docs/reference/gobject/glib-mkenums.xml    |  4 +++-
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/docs/reference/gobject/glib-genmarshal.xml b/docs/reference/gobject/glib-genmarshal.xml
index 2b5ce0e9d..2b3e86fdc 100644
--- a/docs/reference/gobject/glib-genmarshal.xml
+++ b/docs/reference/gobject/glib-genmarshal.xml
@@ -449,7 +449,23 @@ mainlib = library('project',
 )
 </programlisting></informalexample>
 <para>
-For more information, see the <ulink url="https://mesonbuild.com/Gnome-module.html#gnomegenmarshal">Meson
+Additionally, if you are including the generated header file inside a build
+target that depends on the library you just built, you must ensure that the
+internal dependency includes the generated header as a required source file:
+</para>
+<informalexample><programlisting>
+mainlib_dep = declare_dependency(sources: marshal_files[1], link_with: mainlib)
+</programlisting></informalexample>
+<para>
+You should not include the generated source file as well, otherwise it will
+be built separately for every target that depends on it, causing build
+failures. To know more about why all this is required, please refer to the
+<ulink url="https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers">
+corresponding Meson FAQ entry</ulink>.
+</para>
+<para>
+For more information on how to use the method, see the
+<ulink url="https://mesonbuild.com/Gnome-module.html#gnomegenmarshal">Meson
 documentation for <literal>gnome.genmarshal()</literal></ulink>.
 </para>
 </refsect1>
diff --git a/docs/reference/gobject/glib-mkenums.xml b/docs/reference/gobject/glib-mkenums.xml
index ef0d7347b..9dac8217d 100644
--- a/docs/reference/gobject/glib-mkenums.xml
+++ b/docs/reference/gobject/glib-mkenums.xml
@@ -530,7 +530,9 @@ mainlib_dep = declare_dependency(sources: enum_files[1], link_with: mainlib)
 <para>
 You should not include the generated source file as well, otherwise it will
 be built separately for every target that depends on it, causing build
-failures.
+failures. To know more about why all this is required, please refer to the
+<ulink url="https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers">
+corresponding Meson FAQ entry</ulink>.
 </para>
 
 <para>