It's not exactly ambiguity, but I know I find it frustrating to read examples for language X and see oh, everybody (often even in presentations, blog pages, documentation) says foo.bar + baz.quux but you can't actually write that, what they meant was
And if you're stupid enough to just write foo.bar + baz.quux well that's nonsense and the compiler diagnostics won't have any suggestions for how to fix it, what a buffoon you are.
I really don't enjoy this, like the trend for "narrative" cookery recipe style documentation where we're shown how to Quux a Baz [often with fragments that don't compile] in the library but given no indication whether we can Quux a Doodad or even whether that's a feature of the library's Baz or Quux or really what's going on, but hey, the author got to tell us about their trip to Tuscany so that's nice. Javadoc isn't perfect, but it's so much better than this.
tialaramex|11 months ago
I really don't enjoy this, like the trend for "narrative" cookery recipe style documentation where we're shown how to Quux a Baz [often with fragments that don't compile] in the library but given no indication whether we can Quux a Doodad or even whether that's a feature of the library's Baz or Quux or really what's going on, but hey, the author got to tell us about their trip to Tuscany so that's nice. Javadoc isn't perfect, but it's so much better than this.