From c06ba2665a64bff825193af71416ccb4811cf204 Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Sat, 27 Jul 2019 17:22:39 +0100
Subject: [PATCH] doc/concepts.tex: Clearly distinguish between types and
 classes.

C++ bungles this one badly, but we can do better.
---
 doc/concepts.tex | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/doc/concepts.tex b/doc/concepts.tex
index 58f781a..39dfd2e 100644
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -345,6 +345,9 @@ details.
 
 \subsection{C language integration} \label{sec:concepts.classes.c}
 
+It is very important to distinguish compile-time C \emph{types} from Sod's
+run-time \emph{classes}: see \xref{sec:concepts.classes}.
+
 For each class~$C$, the Sod translator defines a C type, the \emph{class
 type}, with the same name.  This is the usual type used when considering an
 object as an instance of class~$C$.  No entire object will normally have a
@@ -354,6 +357,10 @@ class type,\footnote{%
   chains.  See \xref{sec:structures.layout} for the full details.} %
 so access to instances is almost always via pointers.
 
+Usually, a value of type pointer-to-class-type of class~$C$ will point into
+an instance of class $C$.  However, clever (or foolish) use of pointer
+conversions can invalidate this relationship.
+
 \subsubsection{Access to slots}
 The class type for a class~$C$ is actually a structure.  It contains one
 member for each class in $C$'s superclass chain, named with that class's
-- 
2.11.0

