Here is just one example. Can you tell from the StreamingMarkupBuilder documentation how it works? I bet no. After looking through the code snippets on the page and figuring out I could not understand a line of code there, I wondered what is the mkp variable that appears twice on the page.
It took me some time to get through the Groovy class hierarchy up to the BaseMarkupBuilder.java just to find the mkp namespace declaration.
namespaces.put("mkp", "http://www.codehaus.org/Groovy/markup/keywords"); // pseudo namespace for markup keywords
After googling for mkp markup keywords, I found a page that explains in a few words the design of markup builders. Nothing more, nothing less. Now, I know everything I had to know about mkp and markup builders. The thing is, it is a post of the developer who just committed the markup builders feature. The documentation is supposed to be better that that but it not even worse, it is blatantly misleading.