Somebody (a pretty advanced user) just asked me in #javaposse why NetBeans code completion doesn't show the real
argument names for JDK APIs.

Turns out his Java Platform didn't have a Sources zip configured - which I guess is what NetBeans needs to discover the
real parameter names, since they aren't in the jars.

This isn't at all obvious. Can we make this more discoverable?

One simple idea might be that in the Completion Documentation popup, we could put a message that explains this. E.g.
BEFORE the method signature at the top, list a message in italics which says something like that:

Cannot show actual parameter names because the current Java platform does not have a source .zip configured. Go to Tools
| Java Platform to repair. More Info...   (More Info could be a hyperlink which when clicked opens up a help topic
explaining how to configure the sources zip - where to download it from etc.)

Yes, on the one hand it might be annoying for users to have that message "in the way" when trying to look at code
completion, but on the other hand, I don't think anyone who's actually trying to read the code documentation will want
to leave things unconfigured. It might help a lot of people who think NetBeans is broken.

I've filed this as an Enhancement, but what I'm really trying to report here is a usability bug, and my proposed
enhancement is only one possible solution for the usability bug.