Replace the `init' class-slot function with an `init' message.

[sod] / lib / sod.3

diff --git a/lib/sod.3 b/lib/sod.3
index 5908eb74bd689e4bbd3fe516b95957d3c53b7cc9..b713d57f1f0e9aa6dfe7e5ca68215cfa00535ef0 100644 (file)
--- a/lib/sod.3
+++ b/lib/sod.3
@@ -92,6 +92,24 @@ sod \- Sensible Object Design runtime library
 .BI "const SodClass *" cls ,
 .BI "const void *" obj );
 .PP
+.IB cls " *" \c
+.B SOD_INIT(\c
+.IB cls ,
+.BI "void *" p ,
+.IB keywords );
+.br
+.B void *\c
+.B sod_init(\c
+.BI "const SodClass *" cls ,
+.BI "void *" p ,
+.B ...);
+.br
+.B void *\c
+.B sod_initv(\c
+.BI "const SodClass *" cls ,
+.BI "void *" p ,
+.BI "va_list " ap );
+.br
 .B SOD_DECL(\c
 .IB cls ,
 .IB var );
@@ -336,6 +354,55 @@ manage the standard steps along
 an instance's lifecycle.
 .PP
 The
+.B SOD_INIT
+macro,
+and the
+.B sod_init
+and
+.B sod_initv
+functions,
+imprint and initialize an instance of a class
+.I cls
+in the storage starting at address
+.IR p .
+.PP
+The direct class for the new instance is specified as
+a class name to
+.BR SOD_INIT ,
+or a pointer to a class object to the functions.
+.PP
+Keyword arguments for the initialization message may be provided.
+The
+.B SOD_INIT
+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_initv
+expects the keywords to be passed indirectly,
+through the captured argument-tail cursor
+.IR ap .
+.PP
+The return value is an instance pointer for the class
+.IR cls ;
+the
+.B SOD_INIT
+macro will have converted it to the correct type,
+so it should probably be used where possible.
+In fact, this is guaranteed to be equal to
+.I p
+by the layout rules described in
+.BR sod-structs (3).
+.PP
+The
 .B SOD_DECL
 macro declares and initializes an instance
 with automatic storage duration.
@@ -360,6 +427,7 @@ exits the scope of the declaration.
 .
 .\"--------------------------------------------------------------------------
 .SH SEE ALSO
+.BR keyword (3),
 .BR sod (1),
 .BR sod-structs (3).
 .