Whoever eventually figures out the obvious-yet-hidden confluence between cucumber-style BDD 'stories' and javadoc-style documentation is going to make a big splash in the word of programming. I can only hope it's me :)
I think this could be another brilliant addition to the "documentation view". Imagine a multi-tabbed documentation pane. The first tab lets you write normal comments, but in another one you could write doctests like the example you gave, or even assertion of pre and post conditions.