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.

Smart.JavaDoc

The major features of Smart.JavaDoc are:

• Close to WYSIWYG mode of JavaDoc comment editor (according to HTML output provided by standard JavaDoc doclet);
• Rich HTML editing capabilities (Smart.JavaDoc does not support whole set of HTML tags. However, the supported set is quite enough for creation of professional quality documentation);
• Ability to discover and visually highlight JavaDoc conflicts and errors (such as unsupported tags, parameters and throws conflicts, missing tags etc);
• Ability to easily correct found JavaDoc conflicts and errors;
• Rich functionality of JavaDoc comment structure management (adding specific tags, adding all required tags, removing all invalid and unused tags, tags renaming may be performed in couple of clicks);
• Convenient functionality for navigation and instant accessing members for which JavaDoc comments should be created;
• Ability to filter members used for documentation creation via advanced Java Structure Component;
• Ability to perform two-way editing of JavaDoc comment - using both Smart.JavaDoc and usual Java source editor;
• Ability to browse source code while editing JavaDoc;
• Ability to instantly get preview of JavaDoc comment will be generated;
• Sophisticated multilevel undo/redo support.

Smart.JavaDoc User Interface

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

It consists of two major parts:

• Java Structure View, which allows you easily navigate between members for which JavaDoc comment should be generated;
• JavaDoc View, intended to provide JavaDoc comment editing and previewing.

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.

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:

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>

4. 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;
5. 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

6. 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

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

• Tags -actions group provides ability to manipulate the JavaDoc structure by adding, editing or removing particular JavaDoc tags.

• Font - actions group provides ability to apply appropriate font size and family to the currently selected block of text;
• Font Style -actions group provides ability to apply appropriate font style (bold, italic, underline and subscript/superscript ones) to the currently selected block of text;

• Format Painter - a tool similar to one can be found in Microsoft Word. Allows performing of quick copying of formatting style from one text fragment to another one;
• Paragraph Alignment - actions group provides ability to set alignment of paragraph;
• Bullets and Numbering - actions group provides ability to convert currently selected code fragment to a list (either numbered or unnumbered);

• Insert Objects -actions group that provides ability to insert various HTML objects.
  The following objects are supported:
  1. Link - corresponds to the JavaDoc @link tag. The user is able to specify properties of a new link or change them for existing one by using Link Properties Dialog

  2. Hyperlink - corresponds to HTML <a href=…> tag;
  3. Horizontal line - corresponds to HTML <hr> tag;
  4. Line Break - corresponds to HTML <br> tag;
  5. Border - applies appropriate HTML style to the current paragraph;
  6. Image - corresponds to HTML <img> tag. The user is able to specify properties of a newly created image or change them for existing one using the Image Properties Dialog

  7. Insert Symbol - allows to insert special symbol to JavaDoc comment using the Insert Special Symbol dialog

• Colors -actions group which provides ability to specify foreground and background color for the selected fragment of code;
• Options - provides ability to enable/disable displaying of the preview panel;
• Navigation - includes two actions those allow navigation to the next/previous member of Java file. These actions may be invoked using Ctrl+Page Down and Ctrl+Page Up shortcuts, respectively;
• Block Style -actions group which provides ability to specify style of the text block - paragraph (<p>), preformatted block (<pre>), code (<code>) or variable width (<var>);

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

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

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.

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!