Index: library/lib/doc-tools.tcl
===================================================================
diff -u -rdbddbce63d4a499de52ff07fdc63c02017960c79 -rcabb7fe9c303839d53970b59262f9ae416aef2eb
--- library/lib/doc-tools.tcl	(.../doc-tools.tcl)	(revision dbddbce63d4a499de52ff07fdc63c02017960c79)
+++ library/lib/doc-tools.tcl	(.../doc-tools.tcl)	(revision cabb7fe9c303839d53970b59262f9ae416aef2eb)
@@ -1549,6 +1549,7 @@
       :method assign {domain prop value} {
 	set current_entity [$domain current_entity]
 	set scope [expr {[$current_entity info is class]?"object 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]
 	}
@@ -1629,7 +1630,8 @@
 	}
 
 	if {[catch {
-	  set actions [${:current_entity} event=process $line]
+	  puts stderr "PROCESS ${:current_entity} event=process $line"
+	  ${:current_entity} event=process $line
 	} failure]} {
 	  puts stderr ERRORINFO=$::errorInfo
 	  :fastforward
@@ -1638,6 +1640,11 @@
       if {!$is_first_iteration} {
 	${:current_entity} on_exit $line
       }
+
+      if {[${:processed_section} info mixinof -scope object ${:current_entity}] ne ""} {
+	set scope [expr {[${:current_entity} info is class]?"object":""}]
+	${:current_entity} {*}$scope mixin delete ${:processed_section}
+      }
       
       if {$failure ne ""} {
 	error $failure
@@ -1711,6 +1718,7 @@
     :forward event=parse %self {% subst {parse@${:current_comment_line_type}}} 
     :method event=next {line} {
       set next_section [[${:block_parser} processed_section] next_comment_section]
+      puts stderr "NEXT [${:block_parser} processed_section] [$next_section], [[current] info mixin]"
       :on_exit $line
       
       ${:block_parser} rewind
@@ -1751,6 +1759,7 @@
 	  '[namespace tail [:info class]]'
 	}]] throw
       }
+      puts stderr ":$tag [lrange $line 1 end]"
       :$tag [lrange $line 1 end]
     }
 
@@ -1840,7 +1849,7 @@
 		'[namespace tail [$partof_entity info class]]'
 	      }]] throw
 	    }
-	    #	  puts stderr "1. $partof_entity $tag $nq_name {*}$args"
+	    puts stderr "1. $partof_entity $tag $nq_name {*}$args"
 	    set current_entity [$partof_entity $tag $nq_name {*}$args]
 	    
 	  } else {
@@ -1917,8 +1926,19 @@
 	tag->tag	next
       } {
 	# realise the parse events specific to the substates of description
-	# :method parse@tag {line} {;}
-	# :method parse@text {line} {;}
+	:method on_enter {line} {
+	  puts stderr "ENTERING part $line, current section [${:block_parser} processed_section]"
+	  unset -nocomplain :current_part
+	  next
+	}
+	:method parse@tag {line} {
+	  puts stderr "PART parse@tag [current]"
+	  set :current_part [next]
+	}
+	:method parse@text {line} {
+	  puts stderr "PART parse@text [current]"
+	  ${:current_part} @doc add $line end
+	}
 	# :method parse@space {line} {;}
       }
 }
Index: tests/doc.tcl
===================================================================
diff -u -r41cb47a822a9cba7bb25249cf7096078aece68b1 -rcabb7fe9c303839d53970b59262f9ae416aef2eb
--- tests/doc.tcl	(.../doc.tcl)	(revision 41cb47a822a9cba7bb25249cf7096078aece68b1)
+++ tests/doc.tcl	(.../doc.tcl)	(revision cabb7fe9c303839d53970b59262f9ae416aef2eb)
@@ -134,7 +134,7 @@
   set block {
     {}
   }
-  CommentBlockParser process $block
+
   ? [list StyleViolation thrown_by? [list CommentBlockParser process $block]] 1
 
   #
@@ -153,12 +153,14 @@
    {command ::cc}
    {}
   }
+
   ? [list StyleViolation thrown_by? [list CommentBlockParser process $block]] 1
 
   set block {
     {@command ::cc}
     {some description}
   }
+
   ? [list StyleViolation thrown_by? [list CommentBlockParser process $block]] 1
 
  set block {
@@ -337,11 +339,10 @@
   set entity [CommentBlockParser process $block]
   ? [list ::nsf::is $entity object] 1
   ? [list $entity info is type ::nx::doc::@class] 1
-  ? [list $entity text] "some text on the command";
+  ? [list $entity text] "some text on the class entity";
   ? [list llength [$entity @param]] 1
-  ? [list [$entity @param] info is type ::nx::doc::@param]
-  ? [list [$entity @param] @doc] ""
-exit
+  ? [list [$entity @param] info is type ::nx::doc::@param] 1
+  ? [list [$entity @param] text] "Here, we check whether we can get a valid description block for text spanning multiple lines"
 
   #
   # basic test for in-situ documentation (initcmd block)