From 42b948b19e8a99b20630fbd8e2d424df4c9581bd Mon Sep 17 00:00:00 2001
From: Gennaro Prota <gennaro.prota@gmail.com>
Date: Thu, 13 Aug 2026 11:23:20 +0200
Subject: [PATCH] Document that the definition file needs the archive headers

`BOOST_CLASS_EXPORT_IMPLEMENT` instantiates serialization code only for
the archive classes whose headers its translation unit has seen, so a
definition file which includes none of them instantiates nothing, and
serializing a pointer to the class throws `unregistered_class` at run
time.  The rule was stated for `BOOST_CLASS_EXPORT`, but both passages
which send the reader to the `_KEY` and `_IMPLEMENT` pair presented that
split as the answer to the include ordering problem without saying that
the definition file still has to follow it.

Refs #327.
---
 doc/special.html | 11 +++++++++++
 doc/traits.html  |  7 +++++--
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/doc/special.html b/doc/special.html
index a3144df41..b9b854ee6 100644
--- a/doc/special.html
+++ b/doc/special.html
@@ -444,6 +444,17 @@ <h3><a name="export">Exporting Class Serialization</a></h3>
 <code style="white-space: normal">BOOST_CLASS_EXPORT_IMPLEMENT</code>
 in the class definition file.
 
+<p>
+This makes the rule easy to follow but does not remove it.  The definition
+file has to include the archive class headers itself, before
+<code style="white-space: normal">BOOST_CLASS_EXPORT_IMPLEMENT</code>
+is invoked, just as it would for
+<code style="white-space: normal">BOOST_CLASS_EXPORT</code>.
+A definition file which includes none of them instantiates no serialization
+code at all, and serializing a pointer to such a class then throws
+<code style="white-space: normal">unregistered_class</code>
+when the program is run.
+
 <p>
 This system has certain implications for placing code in static or shared
 libraries.  Placing <code style="white-space: normal">BOOST_CLASS_EXPORT</code>
diff --git a/doc/traits.html b/doc/traits.html
index 7f4e65f9a..cad624d45 100644
--- a/doc/traits.html
+++ b/doc/traits.html
@@ -247,8 +247,11 @@ <h3><a name="export">Export Key</a></h3>
 This is addressed by invoking 
 <code style="white-space: normal">BOOST_CLASS_EXPORT_IMPLEMENT(T)</code>
 in the file which defines (implements) the class T.
-This ensures that code for the derived class T will
-be explicitly instantiated.
+That instantiates the code for the archive classes whose headers the file
+includes, so the file has to include them before the macro is invoked.
+See
+<a href="special.html#export">Exporting Class Serialization</a>
+for the details, and for what happens when it includes none of them.
 <li> There needs to be some sort of identifier which can
 be used to select the code to be invoked when the object
 is loaded.