Community
Participate
Working Groups
A warning like "finally block does not complete normally" isn't very self- explanatory for less experienced Java developers. It would be nice if each warning/error had a longer explanation associated with it. In this case, the longer description might read: "This warning is caused by code such as the following: try { ... } finally { return true; } This code is problematic because any exception thrown within the try block will be ignored. Consider moving the return statement outside of the finally block." Findbugs (http://findbugs.sf.net) is a good example of a tool that includes this kind of detailed explanation for each of the problems for which it checks. In terms of the UI implementation, I would like to be able to hover over the warning/error and press F2 at which point the more detailed explanation would pop up.
On plan for 3.5, targeting M5
Small clarification: this is time permitting only for M5. Typically, this is an area where we would love to get some community help to provide contents (and we focus on the infrastructure).
Daniel - if we did provide some structure for recording extra information on problems, would you be interested in contributing to the problem descriptions ?
In the Object Teams Development Tooling we took a slightly different path for providing more help regarding error messages: each error message contains the number of the paragraph in the language definition being offended by the error. The context menu on the problem provides navigation to the snippet from the language definition (http://www.objectteams.org/def/1.2/index.html), which contains explanation and for some parts small examples, too. The text is provided as browsable html with lots of cross-references. Now, the JLS isn't really such a nice read. Does anybody know a text that defines Java in ways that could be useful in this respect? Perhaps the book "Java Precisely", but from that only an old version is freely available/online, which doesn't even seem to provide enough information for this issue. If someone knows a suitable text to link to, we could contribute the (existing) implementation for linking problems to html snippets. If you start all the content from scratch I'm afraid it will be a really huge effort, I mean we're talking about roughly 600 little essays, yes?? Perhaps, the situation is different if you talk about errors (violations against the language) or warnings (tool implementor thought you should not do what you are doing). Perhaps, when restricting this issue to warnings, it is actually feasible and helpful to write these specific little "essays". The number of configurable warnings is still below 64, isn't it? :)
Not for 3.5
I guess bug 149562 is another candidate for an error where additional explanation would be rather helpful. I just ran into that issue and was *sure* this is a bug - until I found bug 207915.
Adding a couple of Cc's and moving to JDT/UI to revive this issue. First: Till, Michael, do you recall who brought this up during the BoF at ECE / who else was interested in this? Everyone else: new relevance has been reported because some problem messages regarding null type annotations pose particular difficulties -- users are requesting to get more help on those. OTOH, any solution should be open to work for any kind of JDT-reported problem. Moving to JDT/UI because of a small new idea: JDT/UI could provide a new extension point for "problem explanation providers". Since JDT/Core's IProblems are API, the provider would simply be passed the problem ID, and optionally answers something to help the user. If for a particular problem a registered provider announces additional help, then problem hovers / context menus etc could offer a "Show Explanation" option. At this point I'm not sure if the provider should: - simply provide HTML to be shown in a common "Problem Explanation" view (which could also be linked to the selected problem), or - implement an action to show more info in whatever way it deems appropriate (e.g., opening a web browser on a provided URL). Browser would have the advantage to enable wiki based content, but requires to be online. Also wikitext format (offline) would be interesting, but JDT/UI cannot depend on Mylyn Wikitext. Individual explanation providers, however, still could. Another question: how to deal with the possible situation of several explanation providers contributing to the same problem ID, but here we're discussing a luxury problem :) (a little selector popup could perhaps suffice here). In the previous epoch this issue stalled due to lack of content. If, however, we start with the clear message that selectively only some problems will have this option attached, then gradual progress should be perfectly supported.
> First: Till, Michael, do you recall who brought this up > during the BoF at ECE / who else was interested in this? I can't remember who exactly, but it was either Tom Schindl, Michael Keppler or Lorenzo Bettini (all participants in our great null analysis BoF), I think. > At this point I'm not sure if the provider should: > - simply provide HTML to be shown in a common "Problem Explanation" view > - implement an action to show more info in whatever way it deems appropriate I was first going to argue that the former unnecessarily limits how such additional detailed descriptions can be provided, and the latter seems more general - BUT then realized that this would probably lead to much consistent UX among providers.. so from a usability PoV, my vote would be to support only Hover-like HTML format, like e.g. how the JavaDoc shows, shown when you F2 *AND* when you hover over the problem marker in the editor on the right, and the line in the Problems view. I'd find this easier and clearer than yet-another view for this purpose. Also, this approach is much more in line with future web IDE, think language server and all... The HTML shown in the Hover could still include links to even more extensive online web page. > Browser would have the advantage to enable wiki based content > Also wikitext format (offline) would be interesting About the Wiki, here is an idea: You could have a default convenience implementation of this new infra which would, given a problem ID and an eclipse.org Wiki page and section ID fetch that HTML (and strip the "frame" decoration; unless it's possible to GET just the HTML "content" from the Wiki), and show it in the Hover... all declarative, without having to write code. > how to deal with the possible situation of several > explanation providers contributing to the same problem ID Start simple, with just showing them all, one after the other. Priorities etc. can come later IMHO.
