From bacf2ba6e7721b6953103f868ffaf2af2c5a817c Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Mon, 5 Aug 2019 10:21:15 +0100
Subject: [PATCH] lib/sod.3: Add missing documentation.

I must have just stopped midway through `SOD_DECL'.  Documentation for
`sod_teardown', `SOD_MAKE' and friends, and `sod_destroy' is entirely
absent.
---
 lib/sod.3 | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)

diff --git a/lib/sod.3 b/lib/sod.3
index b713d57..b6bc6dc 100644
--- a/lib/sod.3
+++ b/lib/sod.3
@@ -110,9 +110,32 @@ sod \- Sensible Object Design runtime library
 .BI "void *" p ,
 .BI "va_list " ap );
 .br
+.B void
+.B sod_teardown(\c
+.BI "void *" p );
+.br
 .B SOD_DECL(\c
 .IB cls ,
 .IB var );
+.br
+.IB cls " *" \c
+.B SOD_MAKE(\c
+.IB cls ,
+.IB keywords );
+.br
+.B void *\c
+.B sod_make(\c
+.BI "const SodClass *" cls ,
+.B ...);
+.br
+.B void *\c
+.B sod_makev(\c
+.BI "const SodClass *" cls ,
+.BI "va_list " ap );
+.br
+.B int
+.B sod_destroy(\c
+.BI "void *" p );
 .PP
 .
 .\"--------------------------------------------------------------------------
@@ -403,6 +426,21 @@ by the layout rules described in
 .BR sod-structs (3).
 .PP
 The
+.B sod_teardown
+function tears down an instance of a class,
+releasing any resources it holds.
+.PP
+This function is a very thin wrapper around sending the
+.B obj.teardown
+message.
+It returns an integer flag.
+A zero value means that the instance is safe to deallocate.
+A nonzero value means that the instance should not be deallocated,
+and that it is safe for the caller to simply forget about it.
+(For example, the object may maintain a reference count,
+and knows that other references remain active.)
+.PP
+The
 .B SOD_DECL
 macro declares and initializes an instance
 with automatic storage duration.
@@ -424,6 +462,95 @@ are set to the appropriate initial values.
 The instance has automatic storage duration:
 pointers to it will become invalid when control
 exits the scope of the declaration.
+.PP
+Keyword arguments for the initialization message may be provided.
+The macro expects a single preprocessor-time argument
+which is a use of one of
+.B KWARGS
+or
+.B NO_KWARGS
+(see
+.BR keyword (3)).
+.PP
+The instance has automatic storage duration:
+pointers to it will become invalid
+when control exits the scope of the declaration.
+If necessary,
+the instance should be torn down before this happens,
+using the
+.B sod_teardown
+function.
+.PP
+The
+.B SOD_MAKE
+macro,
+and the
+.B sod_make
+and
+.B sod_makev
+functions,
+construct and return a pointer to a new instance of a class.
+.PP
+The direct class for the new instance is specified as a class name to
+.BR SOD_MAKE ,
+or as a class object to the functions.
+.PP
+Keyword arguments for the initialization message may be provided.
+The
+.B SOD_MAKE
+macro expects a single preprocessor-time argument
+which is a use of one of
+.B KWARGS
+or
+.B NO_KWARGS
+(see
+.BR keyword (3));
+the
+.B sod_init
+function expects the keywords as
+a variable-length argument tail;
+and
+.B sod_makev
+expects the keywords to be passed indirectly,
+through the captured argument-tail cursor
+.IR ap .
+.PP
+Storage for the new instance will have been allocated
+using the standard
+.BR malloc (3)
+function.
+The easiest way to destroy the instance,
+when it is no longer needed,
+is probably to call the
+.B sod_destroy
+function.
+.PP
+The return value is an instance pointer for the class
+.IR cls ;
+the
+.B SOD_MAKE
+macro will have converted it to the correct type,
+so it should probably be used where possible.
+.PP
+The
+.B sod_destroy
+function tears down and frees an instance allocated using
+.BR malloc (3).
+.PP
+The pointer
+.I p
+should be an instance pointer,
+i.e., a pointer to any of an instance's chains.
+The instance is torn down,
+by sending it the
+.B obj.teardown
+message.
+If the instance reports itself ready for deallocation,
+then its storage is released using
+.BR free (3).
+The return value is the value returned by the
+.B obj.teardown
+message.
 .
 .\"--------------------------------------------------------------------------
 .SH SEE ALSO
-- 
2.11.0