Smart.JavaDoc - Pro!

Creation and editing of source code documentation is an important part of the development process. Unfortunately, JBuilder provides very basic support for this so developer is forced to create the entire JavaDoc comments markup manually.

To significantly increase productivity of source code documentation creation, to reduce amount of possible errors those can occur during this process and maintain documentation to be up-to-date after re-factorings, Productivity! offers very powerful tool intended to provide of visual JavaDoc editing.

The Smart.JavaDoc tool offers rich JavaDoc creation, navigation and editing functionality. It represents additional viewer for Java files and is accessible via appropriate tab at the bottom of the editor.


The major features of Smart.JavaDoc are:

Smart.JavaDoc User Interface

The Smart.JavaDoc tool is an additional viewer available for Java files.

It consists of two major parts:

Smart.JavaDoc Java Structure View
Smart.JavaDoc Java Structure View

The Java Structure View offered by Smart.JavaDoc is similar to one provided for Java files. The main difference is that all unimportant and not suitable members are filtered out from its view. There are two additional actions, those allows to navigate to the next/previous member of Java Structure View. These actions may be invoked using Ctrl+Page Down and Ctrl+Page Up shortcuts, respectively. Please note that these shortcuts are operational even if Java Structure View is not visible.

The JavaDoc View contains toolbar with set of actions used for JavaDoc editing, the JavaDoc editor and, optionally, the preview panel.

Smart.JavaDoc View with Source Code View
Smart.JavaDoc View with Source Code View

There is ability to showing/hiding of the preview panel using the Show/hide preview pane button on the Smart.JavaDoc toolbar.

The preview panel consists of two tabs. The Source one allows you quickly view source code for the currently edited member as well as for the whole file.

The HTML tab contains live preview of the JavaDoc comment that will be generated for current member.

Smart.JavaDoc View with JavaDoc Comment Preview
Smart.JavaDoc View with JavaDoc Comment Preview

The JavaDoc editor panel includes set of editors (one editor per one JavaDoc tag). Each editor or editors' group is labeled with the name of the tag it belongs to. To navigate to the next/previous tag editor, the Tab (or Ctrl+Down)/Shift+Tab (or Ctrl+Up) shortcuts are provided respectively.

JavaDoc Editing Using Smart.JavaDoc

The Smart.JavaDoc tool offers rich functionality for WYSIWYG editing of the JavaDoc comment in form close to one will be generated by standard JavaDoc doclet and in turn redred by Help Viewer.

Editing of JavaDoc is started by activation of Smart.JavaDoc using appropriate tab at the bottom of the editor. Smart.JavaDoc first tries to discover member in the current caret position and offers editing of JavaDoc comment for it. If there are no JavaDoc comment exists for the current source code member, the default JavaDoc template for all suitable tags is offered. If JavaDoc comment exists, Smart.JavaDoc will show editors only for tags defined in it.

Changes made by user while editing the JavaDoc comment are written to the source file on closing the Smart.JavaDoc tab, on selection of another member (class, field or method) or by saving the document.

Please note that Smart.JavaDoc may perform conversion of some unsupported tags found in JavaDoc comment.

The following are limitations of Smart.JavaDoc regarding support of HTML tags:

  1. Smart.JavaDoc doesn't support the following HTML tags so it skips and ignores them:

    <base>, <basefont>, <body>, <html>, <title>, <meta>, <script>, <style>, <head>, <applet>, <object>, <frame>, <noframes>

  2. The following tags are partially supported by Smart.JavaDoc - they will be displayed but in some cases they may be edited incorrectly:

    <form>, <input>, <option>, <textarea>, <table>, <td>, <tr>, <th>

  3. There is set of tags those will be replaced by equivalent ones:
  4. Original Tag Replacing Tag
    <em> <i>
    <strong> <b>
    <address> <i>
    <cite> <i>
    <small> <ont size=10>
    <big> <font size=18>
    <div> <p>
    <dt> <p>
    <blockquote> <p>
    <tt> <code>
  5. Smart.JavaDoc does not support nesting of container tags like <p>, <pre>, <ul>, <ol>, <div>, <dt>, <table>. If JavaDoc comment to be edited contains such nested structures, they will be translated to linear ones, if possible;
  6. If the color attributes are not set for the following tags, Smart.JavaDoc artificially adds them to allow visual recognition of the tags content. These artificial colors are temporary ones and will not appear in the resulting JavaDoc.
    Tag Color Assigned
    <pre> Green
    <var> Maroon
    <anchor> Blue
    <code> Navy
  7. 6. Smart.JavaDoc doesn't support paragraph align attributes for the following tags: <pre>, <ul>, <ol>, <table>;

Also, please note that Smart.JavaDoc considers all words starting from @ as JavaDoc tags.

Smart.JavaDoc Toolbar

Most of the actions accessible for JavaDoc editing are provided by Smart.JavaDoc toolbar.

Smart.JavaDoc Toolbar
Smart.JavaDoc Toolbar

The following groups of actions can be found in the Smart.JavaDoc toolbar:

There is ability to specify which actions group should be visible on the Smart.JavaDoc toolbar using the toolbar context menu.

Controlling Smart.JavaDoc Toolbar
Controlling Smart.JavaDoc Toolbar

JavaDoc Errors Highlighting

The Smart.JavaDoc tool provides rich functionality that allows detecting whether errors or conflicts between Java code definition and corresponding JavaDoc exist.

If some error or conflict is detected, Smart.JavaDoc highlights appropriate element using the underline with style and color corresponding to the issue priority. The reason of the highlighted issue can be found in the hint that appears when mouse cursor is placed over the highlighted element.

JavaDoc Comments Errors Detection
JavaDoc Comments Errors Detection

You can easily fix found errors utilizing appropriate commands available from the popup menu or from toolbar. Using them you can add, remove or edit required JavaDoc tags.

Smart.JavaDoc Shortcuts

There are a lot of actions provided by Smart.JavaDoc those are accessible using keyboard shortcuts. The following table summarizes these actions along with corresponding shortcuts.

Action Shortcut
Copy to clipboardCtrl+C
Cut to clipboardCtrl+X
Paste from clipboardCtrl+V
Select allCtrl+A
Insert new paragraph / Insert new line in the PRE blockEnter
Word leftCtrl+Left
Word rightCtrl+Right
Select word leftCtrl+Shift+Left
Select word rightCtrl+Shift+Right
Go to start of lineHome
Go to start of documentCtrl+Home
Go to end of lineEnd
Go to end of documentCtrl+End
Select to line startShift+Home
Select to document startShift+Ctrl+Home
Select to line endShift+End
Select to document endShift+Ctrl+End
Go to line aboveUp
Go to line belowDown
Select to line aboveShift+Up
Select to line belowShift+Down
Increase paragraph indentCtrl+Tab
Decrease paragraph indentCtrl+Shift+Tab
Go to the next tagTab or Ctrl+Down
Go to the previous tagShift+Tab or Ctrl+Up
Go to the next memberCtrl+Page Up
Go to the next memberCtrl+Page Down
On link or image - activate property action Otherwise - select paragraphMouse-double-click
Set selected text BOLD/DEFAULTCtrl+B
Set selected text ITALIC/DEFAULTCtrl+I
Set selected text UNDERLINE/DEFAULTCtrl+U
Insert Horizontal ruler (<hr>)Ctrl+L
Insert line break (<BR>)Ctrl+Enter
Format painterMouse click - to copy format, mouse click to paste format, Esc or click on button to clear

Options Dependency

Behavior and properties of Smart.JavaDoc can be customized using the Editor Options | Productivity! | Smart.JavaDoc property page.

See also: Productivity! Tools , Customizing Productivity!