From 6a590fd098f39b15d359a2320bcee03439f7d594 Mon Sep 17 00:00:00 2001
Message-Id: <6a590fd098f39b15d359a2320bcee03439f7d594.1716868256.git.mdw@distorted.org.uk>
From: Mark Wooding <mdw@chiark.greenend.org.uk>
Date: Tue, 25 Aug 2015 10:25:30 +0100
Subject: [PATCH] lib/sod.[ch]: Name instance arguments `obj', not `p'.
Organization: Straylight/Edgeware

From: Mark Wooding <mdw@distorted.org.uk>

In some cases, the documentation already had this right.
---
 lib/sod.c |  9 ++++-----
 lib/sod.h | 50 +++++++++++++++++++++++++++++++++-----------------
 2 files changed, 37 insertions(+), 22 deletions(-)

diff --git a/lib/sod.c b/lib/sod.c
index bcaf6f6..1f6ef2e 100644
--- a/lib/sod.c
+++ b/lib/sod.c
@@ -108,16 +108,15 @@ int sod_subclassp(const SodClass *sub, const SodClass *super)
  *		to know what C or S actually are.
  */
 
-void *sod_convert(const SodClass *cls, const void *p)
+void *sod_convert(const SodClass *cls, const void *obj)
 {
-  const struct sod_instance *inst = p;
+  const struct sod_instance *inst = obj;
   const struct sod_vtable *vt = inst->_vt;
   const SodClass *realcls = vt->_class;
   const struct sod_chain *chain = find_chain(realcls, cls);
 
-  if (!chain)
-    return (0);
-  return ((char *)p - vt->_base + chain->off_ichain);
+  if (!chain) return (0);
+  return ((char *)obj - vt->_base + chain->off_ichain);
 }
 
 /*----- That's all, folks -------------------------------------------------*/
diff --git a/lib/sod.h b/lib/sod.h
index 7f18f35..9b9e611 100644
--- a/lib/sod.h
+++ b/lib/sod.h
@@ -73,7 +73,7 @@ struct sod_chain {
 /* --- @SOD_XCHAIN@ --- *
  *
  * Arguments:	@chead@ = nickname of target chain's head
- *		@p@ = pointer to an instance chain
+ *		@obj@ = pointer to an instance chain
  *
  * Returns:	Pointer to target chain, as a @char *@.
  *
@@ -82,7 +82,7 @@ struct sod_chain {
  *		the automatically-generated upcast macros more palatable.
  */
 
-#define SOD_XCHAIN(chead, p) ((char *)(p) + (p)->_vt->_off_##chead)
+#define SOD_XCHAIN(chead, obj) ((char *)(obj) + (obj)->_vt->_off_##chead)
 
 /* --- @SOD_OFFSETDIFF@ --- *
  *
@@ -101,8 +101,8 @@ struct sod_chain {
  *
  * Arguments:	@cls@ = name of a class
  *		@chead@ = nickname of chain head of @cls@
- *		@p@ = pointer to the @chead@ ichain of an (exact) instance of
- *			@cls@
+ *		@obj@ = pointer to the @chead@ ichain of an (exact) instance
+ *			of @cls@
  *
  * Returns:	A pointer to the instance's base, cast as a pointer to the
  *		ilayout structure.
@@ -119,16 +119,27 @@ struct sod_chain {
  *		necessary to use it safely.
  */
 
-#define SOD_ILAYOUT(cls, chead, p)					\
+#define SOD_ILAYOUT(cls, chead, obj)					\
   ((struct cls##__ilayout *)						\
-   ((char *)(p) - offsetof(struct cls##__ilayout, chead)))
+   ((char *)(obj) - offsetof(struct cls##__ilayout, chead)))
+
+/*----- Utility macros ----------------------------------------------------*/
+
+/* --- @SOD_CLASSOF@ --- *
+ *
+ * Arguments:	@p@ = pointer to an instance chain
+ *
+ * Returns:	A pointer to the instance's class, as a const SodClass.
+ */
+
+#define SOD_CLASSOF(obj) ((const SodClass *)(obj)->_vt->_class)
 
 /* --- @SOD_INSTBASE@ --- *
  *
- * Arguments:	@p@ = pointer to an instance (i.e., the address of one of its
- *			instance chains)
+ * Arguments:	@obj@ = pointer to an instance (i.e., the address of one of
+ *			its instance chains)
  *
- * Returns:	The base address of @p@'s instance layout.
+ * Returns:	The base address of @obj@'s instance layout, as a @void *@.
  *
  * Use:		Finds the base address of an instance.  If you know the
  *		dynamic class of the object then @SOD_ILAYOUT@ is faster.  If
@@ -138,18 +149,23 @@ struct sod_chain {
  *		zeroizing the instance structure.
  */
 
-#define SOD_INSTBASE(p) ((void *)((char *)(p) - (p)->_vt->_base))
-
-/*----- Utility macros ----------------------------------------------------*/
+#define SOD_INSTBASE(obj) ((void *)((char *)(obj) - (obj)->_vt->_base))
 
-/* --- @SOD_CLASSOF@ --- *
+/* --- @SOD_CONVERT@ --- *
  *
- * Arguments:	@p@ = pointer to an instance chain
+ * Arguments:	@cls@ = a class type name
+ *		@const void *obj@ = a pointer to an instance
  *
- * Returns:	A pointer to the instance's class, as a const SodClass.
+ * Returns:	Pointer to appropriate instance ichain, or null if the
+ *		instance isn't of the specified class.
+ *
+ * Use:		This is a simple wrapper around the @sod_convert@, which
+ *		you should see for full details.  It accepts a class type
+ *		name rather than a pointer to a class object, and arranges to
+ *		return a pointer of the correct type.
  */
 
-#define SOD_CLASSOF(p) ((const SodClass *)(p)->_vt->_class)
+#define SOD_CONVERT(cls, obj) ((cls *)sod_convert(cls##__class, (obj)))
 
 /*----- Functions provided ------------------------------------------------*/
 
@@ -188,7 +204,7 @@ extern int sod_subclassp(const SodClass */*sub*/, const SodClass */*super*/);
  *		to know what either C or S actually are.
  */
 
-extern void *sod_convert(const SodClass */*cls*/, const void */*p*/);
+extern void *sod_convert(const SodClass */*cls*/, const void */*obj*/);
 
 /*----- That's all, folks -------------------------------------------------*/
 
-- 
[mdw]