This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

Bug 218953

Summary: Confusing double use of the term "Inspect"
Product: ide Reporter: host <host>
Component: UIAssignee: issues@ide <issues>
Status: NEW ---    
Severity: normal CC: richgunther
Priority: P3    
Version: 7.3   
Hardware: PC   
OS: Mac OS X   
Issue Type: ENHANCEMENT Exception Reporter:

Description host 2012-09-25 09:07:28 UTC
Both in the "Navigate" and the "Source" main menu there is an entry "Inspect". But each of them has quite a different semantics behind them. Therefore wouldn't it be good to rename one of them with a more clearer (distinguishing) name.
Comment 1 Petr Somol 2012-09-25 12:06:31 UTC
It does not sound too confusing to me but I am not a native speaker and may already suffer the effect of "frequent use blindness". Inspect Members and Inspect Hierarchy sounds good to me. Regarding Source->Inspect... and Refactor->Inspect&Transform... I can imagine the word Analyze instead of Inspect.
(when you open Source->Inspect... dialog, the default Use Configuration is set to All Analyzers).

In fact we have more related flaws in the UI, which probably could be improved by coming up with better naming. Now

a) Source->Inspect... opens results in a tab named "Inspector Window"
b) Refactor->Inspect&Transform... opens results in a tab named "Refactoring"
c) Navigate->Inspect->Members opens results in the "Navigator" panel set to "Members" view
d) Navigate->Inspect->Hierarchy opens results in the "Hierarchy" panel
e) Tools->Analyze JavaDoc opens results in a tab named "Analyzer"

I guess b) c) and d) are OK, but a) and e) would better be renamed.
CC-ing Rich for expert opinion.
Comment 2 richgunther 2012-09-25 18:20:06 UTC
Sorry for my ineptitude, but what does each option (on the Source and Navigate menus) actually do?

Comment 3 host 2012-09-25 21:00:53 UTC
Actually, I think, Rich's comment seems to exactly reflect the same understanding problem that I have... :-)
Comment 4 Petr Somol 2012-09-26 16:38:13 UTC
So to summarize which Inspect is which:

a) Source->Inspect... 

provides a wealth of various "inspect configurations", i.e., analysis plans, that can be run on the current Java source code. They do not modify the code, their output is only collected and displayed in a dedicated window in hierarchical form, showing line numbers and explaining what has been found there. These analysis plans include various checks for breaches of recommended coding style, or warnings regarding possible vulnerabilities, warnings that returned values are ignored, etc. This is not about compiler errors, instead it can be considered an optional helper tool that can be used to generally improve the code. The external tool FindBugs is integrated here.

b) Refactor->Inspect&Transform...

actually looks very much the same as a), but collects those analysis plans that are also capable of correcting the identified flaws automatically. Typically these include "rewrite to take use of JDK7 constructs", "organize imports", etc.

The UI of the Inspect dialog in case of a) and b) is actually identical, the only UI difference is in the output windows. In case of a) it is not possible to apply any change in the Inspector panel, while in the b) case there is the Refactor button and preview of proposed changes in the Refactoring panel.

I actually proposed in the past to make things simpler and not to separate the lists of passive and active analyses to two equally looking workflows, but to provide just one "Inspect / Transform" dialog that would provide in unified way all types of analyses, both the passive and active ones. But the user would be able to choose what analyses should be applied, a mix, or just the passive one, or just the active, etc. Then this single dialog could be accessed from Source->Inspect... with passive actions preselected, and from Refactor->Inspect&Transform with active actions preselected. But agreement on this has not been reached yet.

c) Navigate->Inspect->Members

opens a panel that shows all members for the currently focused class. Before 7.3 this opened a modal dialog where the hierarchy was displayed, showing all methods, constructors, variables, fields, inner classes, enums, etc. The modality of the dialog has proved to be a problem that prevented most of users to actually use it. Morover, if had actually been almost equal to the widely used Navigator panel functionality that every Java programmer experiences in NB all the time. See how Navigator contents get updated depending on where the focus/cursor is. There is actually two difference forms of the action:
Navigate->Inspect->Members and Navigate->Inspect->File Members. The difference is very hard to grasp for users, but till now we could not find better wording nor any reasonable way of joining the two. The difference is in that File Members applies to the current file as a whole (and because in Java each file represents just one class, that is the class whose contents are to be shown). Members then applies to whatever is currently under the cursor. So if the cursor is inside the variable type String somewhere in Java source, then the Members action would show the contents of String class.

For 7.3 the Inspect Members dialog(s) has been abandoned and the action has been integrated with the already existing Navigator functionality. 

Inspect Members is related to Inspect Hierarchy, see below. In many IDEs these two are used together, so for 7.3 we decided to improve things in this sense. The rough plan can be seen here:

d) Navigate->Inspect->Hierarchy

opens a panel that shows either supertype or subtype hierarchy for the class in focus. This is actually very important and practical, but before 7.3 it had been also presented in form of modal dialog and thus almost never used. But users quite loudly demand this to be available at all times, so that they may browse quickly through the related class hierarchies and see what is in which ancestor/descendant class (the actual contents are now shown in Navigator panel, see c) comment). So in 7.3 we made both Inspect Members and Inspect Hierarchy panel dockable. They cooperate well also with the JavaDoc panel so from 7.3 it will be very convenient to browse quickly through the various class hierarchies and to see immediately class contents as well as the accompanying JavaDoc information. Now it looks more or less like on the following mockup:
Similarly to c) there is two variants of this action: Navigate->Inspect->Hierarchy and Navigate->Inspect->File Hierarchy.

e) Tools->Analyze JavaDoc opens results in a tab named "Analyzer"

Logically is just another analysis plan that could be integrated into b) UI. It can be applied to a Java source to check whether all methods have proper javadoc comments. It corrects the found deficiencies. The reason why it is not part of b) is historical and technical, because it was created by different people than b) and a slightly different usage pattern has thus been promoted. The difference is in the rather awkward Fix on Next checkbox that in the Analyzer window enables the user to press Next (the button with yellow down arrow) and in this way to apply the proposed changes one after another. The team behind b) did not like this so this is why we ended up with separate windows for b) and e)
Comment 5 richgunther 2012-10-02 19:44:42 UTC
This seems like it's a larger issue than the initial bug.  Do we want to defer on this until we can do a more exhaustive review of the various inspect options?  We are in the process of setting up a UI steering committee for dealing with questions such as this.  Perhaps this would be a good starting task for them? 

I'm putting together the mailing list now.