So, part of the new app is written in groovy. Trying to navigate the groovy docs – I loathe it already. Why? No formal spec. The docs are all written as user guides: “you can do this”, “oh, and you can do this”, “and you can do this”.
Have a look at the languages specification: tricked you! The only way to find it is to ask google. It’s at http://groovy.codehaus.org/jsr/spec/. Have a look at “lexical structure” – go right to the end, section 3.12: “operators”.
Woah! There’s a whole swag of new operators there!
Operator:
.. ..< … *. ?. .&
=~ ==~ ** **= .@
What do they do? Let’s go to Expressions and find out.
Blatttt! You lose! They are just not there. This is shit. “Oh, but it’s a first draft!”. Cool. This language has been in production a while – where’s the current final version? There isn’t one! All you have is a bunch of cookbook pages that (hopefully) cover everything.
The documentation page is useless. I dont want to see a “feature summary”, or “advanced usage”, or “using groovy” or a goddamn “quick reference card”. I want to see a systematic goddamn language specification, so that once I have read it all I know that there won’t be any more “oh, by the way – did you know you could also do this?” buried in it somewhere. Random web pages around the shop means that you can never, never really be sure that you know the subject matter.
Perl is even worse. Screw these kids these days that think they don’t need to document the tweaks they make to their compilers with a language spec. Bet the reason they don’t write one is that they can’t read one.
Paul Murray's SFW Blog 
Perl is worse? How? Not only is the language and its modules intricately documented (the detail is all there, even if it’s sometimes hard to grok), I know exactly where to go and what detail to expect just for any _changes_ to it from version to version.
I’ve never seen a TODO in place of doc – unless you count half-arsed/abandoned experimental modules, none of which ship with perl itself.
Lately I did have a problem with Moose (popular, but not perl core) and method modifiers: the doc only specifies how ‘around’ modifiers are called by Moose, and you’re left guessing if the other types of modifiers work the same way.
I think we just have to accept that all these nifty things get to maturity at their own pace and in their own ways; especially in projects which are largely volunteer driven.
Documentation is especially a distinguishing factor between commercially developed languages and something that’s community/volunteer driven. Not sure if Groovy is the latter or former or some hybrid, but there’s only 2 bugs open for Documentation in jira atm: http://jira.codehaus.org/browse/GROOVY/component/15462
If you don’t raise a task, it’s unlikely to be addressed.