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:
The Smart.JavaDoc tool is an additional viewer available for Java files.
It consists of two major parts:
|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|
There is ability to showing/hiding of the preview panel using the 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|
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.
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:
<base>, <basefont>, <body>, <html>, <title>, <meta>, <script>, <style>, <head>, <applet>, <object>, <frame>, <noframes>
<form>, <input>, <option>, <textarea>, <table>, <td>, <tr>, <th>
|Original Tag||Replacing Tag|
Also, please note that Smart.JavaDoc considers all words starting from @ as JavaDoc tags.
Most of the actions accessible for JavaDoc editing are provided by 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|
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|
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.
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.
|Copy to clipboard||Ctrl+C|
|Cut to clipboard||Ctrl+X|
|Paste from clipboard||Ctrl+V|
|Insert new paragraph / Insert new line in the PRE block||Enter|
|Select word left||Ctrl+Shift+Left|
|Select word right||Ctrl+Shift+Right|
|Go to start of line||Home|
|Go to start of document||Ctrl+Home|
|Go to end of line||End|
|Go to end of document||Ctrl+End|
|Select to line start||Shift+Home|
|Select to document start||Shift+Ctrl+Home|
|Select to line end||Shift+End|
|Select to document end||Shift+Ctrl+End|
|Go to line above||Up|
|Go to line below||Down|
|Select to line above||Shift+Up|
|Select to line below||Shift+Down|
|Increase paragraph indent||Ctrl+Tab|
|Decrease paragraph indent||Ctrl+Shift+Tab|
|Go to the next tag||Tab or Ctrl+Down|
|Go to the previous tag||Shift+Tab or Ctrl+Up|
|Go to the next member||Ctrl+Page Up|
|Go to the next member||Ctrl+Page Down|
|On link or image - activate property action Otherwise - select paragraph||Mouse-double-click|
|Set selected text BOLD/DEFAULT||Ctrl+B|
|Set selected text ITALIC/DEFAULT||Ctrl+I|
|Set selected text UNDERLINE/DEFAULT||Ctrl+U|
|Insert Horizontal ruler (<hr>)||Ctrl+L|
|Insert line break (<BR>)||Ctrl+Enter|
|Format painter||Mouse click - to copy format, mouse click to paste format, Esc or click on button to clear|
Behavior and properties of Smart.JavaDoc can be customized using the Editor Options | Productivity! | Smart.JavaDoc property page.
See also: Productivity! Tools , Customizing Productivity!