Index: doc/Class.man
===================================================================
diff -u -r54cdf1847245e3d6245a740808d1d6923fb78997 -rec55df9eef84e5360997a387c5ec45509c4f15a6
--- doc/Class.man	(.../Class.man)	(revision 54cdf1847245e3d6245a740808d1d6923fb78997)
+++ doc/Class.man	(.../Class.man)	(revision ec55df9eef84e5360997a387c5ec45509c4f15a6)
@@ -361,10 +361,30 @@
 [enum] Finally, the initialization method [method init] is dispatched, if
 available for [arg instance]. [method "init"] can be defined by [arg cls] on
 behalf of its instance [arg instance], e.g., to lay out a
-class-specific initialisation behaviour. Alternatively, or
-additionally, the object [arg instance] may define an per-object
-[method init] on its own.
+class-specific initialisation behaviour.
 
+[example_begin]
+% nx::Class create Foo {:property x}
+% Foo method init {} {set :y [lb]expr {${:x} + 1}[rb]}
+% Foo public method bar {} {return ${:y}}
+% Foo create f1 -x 101
+% f1 cget -x
+101
+% f1 bar
+102
+[example_end]
+
+Alternatively, the object [arg instance] may define an per-object
+[method init] on its own. A per-object [method init] can be chained to
+a class-level [method init] using [cmd nx::next], just like a regular
+method.
+
+[para]
+
+Note that the definition of an [method init] method must contain an
+empty parameter specification, since [method init] is always called
+with an empty argument list.
+
 [list_end]
 
 Object destruction, as triggered by, e.g., an application-level
Index: doc/Object.man
===================================================================
diff -u -r496978cf0b0f707fb82cd16eba99b2e44497e9ed -rec55df9eef84e5360997a387c5ec45509c4f15a6
--- doc/Object.man	(.../Object.man)	(revision 496978cf0b0f707fb82cd16eba99b2e44497e9ed)
+++ doc/Object.man	(.../Object.man)	(revision ec55df9eef84e5360997a387c5ec45509c4f15a6)
@@ -228,27 +228,29 @@
 
 [list_end]
 
-[cmd_def defaultmethod]
+[comment {
+  [cmd_def defaultmethod]
+  
+  [list_begin definitions]
+  
+  [call [arg obj] [cmd defaultmethod]]
 
-[list_begin definitions]
+  This method is called implicitly when the object command is invoked
+  without an argument. By default, the [cmd defaultmethod]
+  implementation returns the fully qualified object name.
 
-[call [arg obj] [cmd defaultmethod]]
+  [example_begin]
+  % Object create ::foo
+  ::foo
+  % ::foo defaultmethod
+  ::foo
+  % ::foo
+  ::foo
+  [example_end]
+  
+  [list_end]
+}]
 
-This method is called implicitly when the object command is invoked
-without an argument. By default, the [cmd defaultmethod]
-implementation returns the fully qualified object name.
-
-[example_begin]
-% Object create ::foo
-::foo
-% ::foo defaultmethod
-::foo
-% ::foo
-::foo
-[example_end]
-
-[list_end]
-
 [cmd_def delete]
 
 [list_begin definitions]
@@ -554,8 +556,9 @@
 
 [list_end]
 
+[comment { 
 [cmd_def init]
-
+  
 [list_begin definitions]
 
 [call [arg obj] [cmd init] [opt "[arg arg] ..."]]
@@ -578,6 +581,7 @@
 102
 [example_end]
 [list_end]
+}]
 
 
 [cmd_def method]
@@ -619,20 +623,6 @@
 
 [list_end]
 
-
-[cmd_def require]
-
-[list_begin definitions]
-
-[call [arg obj] [method require] [method namespace]]
-
-Create a Tcl namespace named after the object [arg obj]. All object
-variables become available as namespace variables.
-
-[include require.man.inc]
-
-[list_end]
-
 [cmd_def property]
 
 [list_begin definitions]
@@ -665,6 +655,19 @@
 
 [list_end]
 
+[cmd_def require]
+
+[list_begin definitions]
+
+[call [arg obj] [method require] [method namespace]]
+
+Create a Tcl namespace named after the object [arg obj]. All object
+variables become available as namespace variables.
+
+[include require.man.inc]
+
+[list_end]
+
 [cmd_def unknown]
 
 [list_begin definitions]