Behavior of Closure in GString needs to be documented

In GROOVY-1665, the behavior of closures in GStrings was changed. However, no documentation was created to inform users of this new behavior. This was a change in behavior that went in as part of Groovy 1.1 Beta 1

The new, undocumented behavior is that closures are evaluated when present in GStrings. If they accept zero arguments, they are "call"ed and the results put in the string. If they accept 1 argument, they are passed a writer, which they should write to. And if they take 2 or more arguments, they throw an exception.

This breaks the principle of least surprise, and needs to be documented. I understand the reason for the change, but EVERY other variable type, when included in a GString, returns the result of a toString() call. This issue came up when I was attempting to debug a method that was being called with a closure argument. I attempted to print the closure "pointer" with the line: println "Closure: $

" which failed with an exception thrown from within the closure.

This behavior is undocumented in the send that it is not referred to on the Groovy page that discusses Strings and GStrings, http://groovy.codehaus.org/Strings

When I searched the Groovy.codehaus.org site for the words "gstring closure", there were no articles discussing this behavior.

I only found out about this behavior when I searched the Jira system, before creating a bug to report what I thought was incorrect behavior.

It is also mentioned in passing the the new "Programming Groovy" book by Venkat.