UEXJavaDoc

Date: 15 JUN 2012 Author: Petr Somol

See also: UEXInspectMembersAndHierarchies.

Problem / Motivation

JavaDoc content is accessible in various contexts throughout NB IDE as a valuable resource. It will become even more important after the planned redesign of Inspect Members and Inspect Hierarchy UI (cf. UEXInspectMembersAndHierarchies). The current implementation is reasonably good, but suffers a couple of UEX problems that should be fixed. See the screenshots showing the current state of JavaDoc display.

Current JavaDoc dockable window in NB 7.2 - note the marked formatting problems
Current JavaDoc shown as pop-up when hovering over members in Navigator in NB 7.2 - note the marked formatting problems
Current JavaDoc panel embedded in Inspect Members dialog in NB 7.2 (Inspect Members to be redesigned in NB 7.3)
  • The emphasis in JavaDoc window should naturally be put on the name of the described entity (method name, class name etc.), but now it is the name of package that captures all attention at first due to large font size and bold weight.
  • the entity name is currently in fact even smaller than the descriptive text below it. It can be seen, e.g., in on-line JavaDoc documents that entities should be shown as the main title of the page, with package name above it emphasized as well but less.
  • Bugzilla issue 209259 focuses on the problem of maximizing valuable vertical space in IDE windows. The current JavaDoc window contains a horizontal toolbar with only a few buttons, which nevertheless consumes up to two lines of JavaDoc text.


Proposed Changes in NetBeans 7.3

To ensure that maximum space is used for displaying valuable information and for easier visual orientation (to promote the importance of entities over packages and over the detailed body text) I propose the following:

  • the formatting of package name should be changed - font size should be reduced to the font size of JavaDoc body text. Keep it as live link, in blue, underlined. Would it be possible instead of one link to have different links to different parts of the package hierarchy depending on where user clicks in the name ? No problem if not.
  • the distance between package name and entity name (JavaDoc title) can be made smaller than is the distance between title and body text. This would save some space and visually connect a little more the package name and entity name. Actually completely removing the one blank line between package name and entity name is an option. But this is not necessary if there are technical difficulties to achieve it.
  • the line with entity name should serve as the main title in JavaDoc window, at the same time it should visually refer to the standard code formatting as it actually is a piece of code. Therefore I suggest to set the line by default in the same font and size as is default in editor window (at any rate it should not be smaller that default editor font size). No change in color scheme - basic color black, links to ascendants or interfaces blue and underlined. However, the entity name itself should be visibly emphasized by bold font weight. I would even suggest a slightly increased font size for it to ensure that this is what would be visually recognizable as the main title. See the mockup image below for LinkedList<E>.
  • Toolbar should be made vertical to save vertical space for JavaDoc text itself. Ideally there should be choice for users to move the toolbar to horizontal or vertical position, but such functionality would require effort that would probably not be worth it; and because the main place for displaying JavaDoc is to be the dockable window under editor window, vertical toolbar is significantly more practical. The saved vertical space IMHO outweighs clearly the possible complaint that the buttons for the previous and next page are now placed above each other instead beside each other, what would look more natural.
  • tooltip on JavaDoc tab should show the name of the displayed entity (the current text "..window shows javadoc for entity under the caret" will not make sense after the JavaDoc window will be used in conjunction with redesigned Inspect Members and Inspect Hierarchy (cf. UEXInspectMembersAndHierarchies). Even now it is misleading if the contents have been shown as result of pressing Ctrl-F1 in Navigator window)
  • in case the JavaDoc pane is displayed as temporary pop-up window on hover over entity in Navogator - Members View, and the JavaDoc text content is extensive, the pop-up window displays a vertical scrollbar. However, there is no way how to scroll; there is no shortcut for that, and any attempt to do it using mouse fails on the fact that moving mouse pointer out of the entity line in Members View closes the pop-up. This is a UEX bug that needs to be resolved. One possible solution could be roughly this: permit the pop-up to gain focus as result of pressing Tab key. When having thus obtained focus, the window would then react to standard arrow keys of mouse scrolls, until Esc is pressed or mouse is clicked outside the window or Tab is pressed to move focus elsewhere.

For illustration of the proposal see the attached mockup picture:

Mockup of proposed JavaDoc formatting in NB 7.3. Note the vertical toolbar, decreased emphasis on package name, increased emphasis on entity name, plus the extra text in the bottom that fits into the window due to the saved space when compared to the equally sized 7.2 window as shown above in this page
Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo