Index: library/lib/doc-tools.tcl
===================================================================
diff -u -rda6586782390b02ed7660b56417c3db00d63d1c3 -r340c1572913656239bb09237b9b1d1b83f6442cb
--- library/lib/doc-tools.tcl	(.../doc-tools.tcl)	(revision da6586782390b02ed7660b56417c3db00d63d1c3)
+++ library/lib/doc-tools.tcl	(.../doc-tools.tcl)	(revision 340c1572913656239bb09237b9b1d1b83f6442cb)
@@ -145,7 +145,7 @@
 	set base "${:prefix}::[namespace tail $mixin]"
 	if {[::nsf::object::exists $base]} {
 	  set scope [expr {[$mixin scope] eq "object" && \
-			       [$base info is class]?"class-object":""}]
+			       [$base info is class]?"class":""}]
 	  dict lappend :active_mixins $base $mixin
 	  $base {*}$scope mixin add $mixin
 	}
@@ -156,7 +156,7 @@
       dict for {base mixins} ${:active_mixins} {
 	foreach m $mixins {
 	  set scope [expr {[$m scope] eq "object" && \
-			       [$base info is class]?"class-object":""}]
+			       [$base info is class]?"class":""}]
 	  $base {*}$scope mixin delete $m
 	}
       }
@@ -464,7 +464,8 @@
 		     -name [lindex $value 0] \
 		     -partof $domain \
 		     -part_attribute [current] \
-		     -@doc [lrange $value 1 end]]
+		     [lrange $value 1 end]]
+	#-@doc [lrange $value 1 end]]
       }
       return $value
     }
@@ -516,9 +517,9 @@
 
     # every Entity must be created with a "@doc" value and can have
     # an optional initcmd 
-    :method objectparameter args {
-      next [list [list @doc:optional __initcmd:initcmd,optional]]
-    }
+    #:method objectparameter args {
+      #next [list [list @doc:optional __initcmd:initcmd,optional]]
+    #}
 
     :class attribute current_project:object,type=::nx::doc::@project,0..1
     :public forward current_project [current] %method
@@ -598,7 +599,11 @@
       return [concat {*}$path]
     }
 
-    :attribute @doc:0..* {set :incremental 1}
+    :attribute @doc:0..* {
+      set :incremental 1
+      set :positional true
+      set :position 1
+    }
     :attribute @see -class ::nx::doc::PartAttribute
 
     :attribute @deprecated:boolean -class ::nx::doc::SwitchAttribute {
@@ -1064,9 +1069,9 @@
 	  set :part_class ::nx::doc::@method
 	}
 
-	:public forward @attribute %self @class-object-attribute
+	:public forward @attribute %self @object-attribute
 	#:forward @param %self @object-param
-	:attribute @class-object-attribute -class ::nx::doc::PartAttribute {
+	:attribute @object-attribute -class ::nx::doc::PartAttribute {
 	  set :part_class ::nx::doc::@param
 	}
 
@@ -1095,8 +1100,8 @@
 	  set :part_class ::nx::doc::@param
 	}
 	
-	:public forward @method %self @class-method
 	:public forward @class-object-method %self @object-method
+	:public forward @class-object-attribute %self @object-attribute
 
 	:public forward @hook %self @class-hook
 	:attribute @class-hook -class ::nx::doc::PartAttribute {
@@ -1105,6 +1110,7 @@
 	  set :part_class ::nx::doc::@method
 	}
 
+	:public forward @method %self @class-method
 	:attribute @class-method -class ::nx::doc::PartAttribute {
 	  :pretty_name "Provided method"
 	  :pretty_plural "Provided methods"
@@ -2387,7 +2393,9 @@
 
     :public class method type=nonempty {name value} {
       if {$value eq ""} {
-	error "An empty value is not allowed for parameter '$name'."
+	return \
+	    -code error \
+	    "An empty value is not allowed for parameter '$name'."
       }
       return $value
     }
@@ -2431,7 +2439,7 @@
         ->source:fpathtype,arg=absolute,slot=[current] \
 	{->nsexported:boolean 0} \
 	{->nsimported:boolean 0} \
-        ->docstring:optional,nonempty,slot=[current] \
+        ->docstring:optional,slot=[current] \
 	->bundle
      ] {
       # peek the currently processed package (if any)
@@ -2795,7 +2803,7 @@
 		    set obj $modifier 
 		    set scope ""
 		    set name ""
-		  } elseif {$modifier eq "class-object"} {
+		  } elseif {$modifier eq "class"} {
 		    set scope $modifier
 		    set name [lindex $definition 4]
 		  } else {
@@ -3841,7 +3849,7 @@
 	    [$box do [list ${name} info method body $methodName]]
       }
       
-      :process=@object $project $entity class-object
+      :process=@object $project $entity class
       
     }
     
@@ -3858,7 +3866,8 @@
       foreach methodName [$box do [list ${name} {*}$scope info methods\
 				       -methodtype scripted \
 				       -callprotection public]] {
-	set tag [join [list {*}$scope method] -]
+	
+	set tag [join [list {*}[expr {$scope eq "class"?"class-object":""}] method] -]
 	# set id [$entity @$tag $methodName]
 	:readin \
 	    -partof_entity $entity \
@@ -3952,7 +3961,7 @@
       set :incremental 1
       :public method assign {domain prop value} {
 	set current_entity [$domain current_entity]
-	set scope [expr {[$current_entity info is class]?"class-object mixin":"mixin"}]
+	set scope [expr {[$current_entity info is class]?"class mixin":"mixin"}]
 	#	puts stderr "Switching: [$current_entity {*}$scope] --> target $value"
 	if {[$domain eval [list info exists :$prop]] && [:get $domain $prop] in [$current_entity {*}$scope]} {
 	  $current_entity {*}$scope delete [:get $domain $prop]
@@ -4063,7 +4072,7 @@
       # 	${:current_entity} {*}$scope mixin delete ${:processed_section}
       # }
 
-      set scope [expr {[${:current_entity} info is class]?"class-object":""}]
+      set scope [expr {[${:current_entity} info is class]?"class":""}]
       set mixins [${:current_entity} {*}$scope info mixin classes]
       if {${:processed_section} in $mixins} {
 	set idx [lsearch -exact $mixins ${:processed_section}]
Index: tests/doc.test
===================================================================
diff -u -rda6586782390b02ed7660b56417c3db00d63d1c3 -r340c1572913656239bb09237b9b1d1b83f6442cb
--- tests/doc.test	(.../doc.test)	(revision da6586782390b02ed7660b56417c3db00d63d1c3)
+++ tests/doc.test	(.../doc.test)	(revision 340c1572913656239bb09237b9b1d1b83f6442cb)
@@ -603,6 +603,12 @@
     #
     # @attribute attr1 Here we can only provide a description block for object parameters
     
+    # @class.object-method {::C sub}
+    #
+    # For now, we have to declare a family of sub methods explicitly
+    # (allows for providing some overview, shared description)
+
+
     # @class.attribute {::C attr1} Here, we could also write '@class.class-attribute \{::C attr1\}', @attribute is a mere forwarder! In the context section, only one-liners are allowed!
     
     # @class.object.attribute {::C foo p1} A short description is ...
@@ -657,6 +663,11 @@
 	return [current method]-$p1-[current]
       }]
       
+      # @.object-method bar
+      #
+      # Before referring to its parts, an entity must exist; so
+      # declare eagerly ...
+
       # @.class-object-method.parameter {bar p1}
       #
       # This extended form allows to describe a method parameter with all
@@ -786,7 +797,7 @@
   #  ? [list $entity as_text] ".. is overruled by a long one ..."
 
   # --testing-- @class-object-attribute attr2 (its non-existance)
-  set entity [@attribute id [@class id ::C] class attr2]
+  set entity [@attribute id [@class id ::C] object attr2]
   ? [list ::nsf::object::exists $entity] 0
   # --testing-- @child-class Foo (its non-existance)
   set entity [@class id ::C::Foo]
@@ -802,13 +813,14 @@
   ? [list ::nsf::object::exists $entity] 0
   set entity [@attribute id $cl class p1]
   ? [list ::nsf::object::exists $entity] 0
-  set entity [@attribute id $cl class p2]
+  set entity [@attribute id $cl object p2]
   ? [list ::nsf::object::exists $entity] 0
 
   #
   # 2) process the initcmd comments (PARSING LEVEL 1)
   #
   
+  puts stderr -----INITCMD------
   ::nsf::configure keepinitcmd true
   eval $script
   ::nsf::configure keepinitcmd false
@@ -818,7 +830,6 @@
 	     -tag @class \
 	     -name ::C \
 	     [::C eval {set :__initcmd}]] _ processed_entities
-  
   # a) existing, but modified ...
   
   set entity [@class id ::C]
@@ -837,15 +848,15 @@
   ? [list ::nsf::object::exists $entity] 1
   ? [list $entity info has type ::nx::doc::@object] 1
   ? [list $entity as_text] "'foo' needs to be defined before referencing any of its parts!"; # still empty!
-  set entity [@attribute id $entity class p1]
+  set entity [@attribute id $entity object p1]
   ? [list ::nsf::object::exists $entity] 1
   ? [list $entity info has type ::nx::doc::@attribute] 1
   ? [list $entity as_text] "The first element in the name list is resolved into a fully qualified (absolute) entity, based on the object owning the initcmd!"
   
   # b) newly added ...
   
   # --testing-- @class-object-attribute attr2
-  set entity [@attribute id [@class id ::C] class attr2]
+  set entity [@attribute id [@class id ::C] object attr2]
   ? [list ::nsf::object::exists $entity] 1
   ? [list $entity info has type ::nx::doc::@attribute] 1
   ? [list $entity as_text] "Carries a short desc only";
@@ -876,7 +887,7 @@
   set entity [@attribute id $cl class p1]
   ? [list ::nsf::object::exists $entity] 1
   ? [list $entity as_text] {This is equivalent to stating "@child-class.class-attribute {Foo p1}"}
-  set entity [@attribute id $cl class p2]
+  set entity [@attribute id $cl object p2]
   ? [list ::nsf::object::exists $entity] 1
   ? [list $entity as_text] "Y"
   
@@ -944,7 +955,7 @@
   ? [list ::nsf::object::exists $entity] 1
   ? [list $entity info has type ::nx::doc::@object] 1
   ? [list $entity as_text] "Adding a line for the first time (not processed in the initcmd phase!)"; # still empty!
-  set entity [@attribute id $entity class p1]
+  set entity [@attribute id $entity object p1]
   ? [list ::nsf::object::exists $entity] 1
   ? [list $entity info has type ::nx::doc::@attribute] 1
   ? [list $entity as_text] {This is equivalent to stating "@class-object-attribute p1"}
@@ -962,7 +973,7 @@
   set entity [@attribute id $cl class p1]
   ? [list ::nsf::object::exists $entity] 1
   ? [list $entity as_text] {This is equivalent to stating "@class-attribute p1"; or '@class.object.attribute {::C Foo p1}' from the top-level.}
-  set entity [@attribute id $cl class p2]
+  set entity [@attribute id $cl object p2]
   ? [list ::nsf::object::exists $entity] 1
   ? [list $entity as_text] ""