I find this kind of features is quite interesting, because API-doc is useful when you need a precise information ("I know there is a function for this, but what's the args order again ?"). When the only doc for a new project I am interested in is javadoc/doxygen, I usually run away.
As a reference, yes. I agree javadocs are little help for the big picture (or for the search problem of not knowing the term to look for).
However, it's much better than no documentation; and having it automatically derived makes it more likely to happen. It's much less work, and how much documentation would we have otherwise? Even if no explicit explanations are added, it's an improvement over nothing.
I think active docs, which you experiment with and see the behaviour as in the django story here, is even better again. (Although, there's little guidance and no explanation in these docs; and I got stack traces when I tried to add something.)
However, the big picture is what is missing - I wonder if there is a way to ease the documentation of this also? That shows the high-level interactions between things. I think part of the problem is that API docs show all the options, but often only 20% are used often, you can get by with even a smaller amount, and get something working with even less. That is, examples of concrete instances of API usage, not all the choices. For example, java.lang.String has a surprising number of methods, but most code doesn't use any of them (most code doesn't manipulate strings).
So, perhaps constraining docs in some way: maybe ranking methods by usage frequency; or designating examples, combining the used subsets of docs into one page. One might generalize this slightly, to show commonly used choices: this would give you the idea that this part is background that's always the same, and these parts are the foreground that changes. i.e. a grammar over the API, of common usage patterns.
This still wouldn't be perfect, but an improvement over purely reference docs; and making it much easier to produce would mean they'd be more of it.
An improvement over this would be game mechanics (I don't mean achievement unlocked BS, but a gradual learning curve, with feedback on how you are doing - puzzles, or active exercises IOW.
I find this kind of features is quite interesting, because API-doc is useful when you need a precise information ("I know there is a function for this, but what's the args order again ?"). When the only doc for a new project I am interested in is javadoc/doxygen, I usually run away.