Writing documentation within the software

The following pieces of source code come from our goodie JNumberField. It is a Java JTextField that only accepts numeric values. This is a very usefull component as it means that within the software no checking of the validity has to be performed when the String taken from the JTextField has to be converted into a number (a double). Also it means that no error messages have to be constructed when the user erroneously types a text into a textfield where only input of a number is meant.
Here are some pieces of the code :

package JosAertsBeans;

import javax.swing.*;
import javax.swing.event.*;
import java.awt.*;
import java.awt.event.*;
import java.awt.Toolkit.*;

public class JNumberField extends JTextField implements KeyListener, CaretListener, FocusListener {

/** Constructor with input for the length of the field. */
public JNumberField (int Columns) {
... }
/** Constructor without input. */
public JNumberField() {
... }
/** Handle the key typed event from the text field. */
public void keyTyped(KeyEvent evtKey) {
... }
/** Transform the contents of the field to a double */
public double getDoubleValue() {
... }

All comments that are included between /** and */ and immediately preceeding the constructor and method declarations are automatically retrieved using the javadoc tool and put into an HTML file.

An additional advantage is that when a reusable component is used for which the source code is not available (think about purchased components), the API will always be available (the seller delivers the contract of the reusable compound), so that the developer can use the component without having to know or understand the actual implementation, and that also this piece of the application (although no source code) is well-documented.

The full HTML page (as automatically retrieved - no manual editing !) of our JNumberField goodie is given below:





JosAertsBeans
Class JNumberField

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--javax.swing.JComponent
                    |
                    +--javax.swing.text.JTextComponent
                          |
                          +--javax.swing.JTextField
                                |
                                +--JosAertsBeans.JNumberField

public class JNumberField
extends javax.swing.JTextField
implements java.awt.event.KeyListener, javax.swing.event.CaretListener, java.awt.event.FocusListener

See Also:
Serialized Form

Inner classes inherited from class javax.swing.JTextField
javax.swing.JTextField.AccessibleJTextField
 
Inner classes inherited from class javax.swing.text.JTextComponent
javax.swing.text.JTextComponent.AccessibleJTextComponent, javax.swing.text.JTextComponent.KeyBinding
 
Inner classes inherited from class javax.swing.JComponent
javax.swing.JComponent.AccessibleJComponent
 
Fields inherited from class javax.swing.JTextField
notifyAction
 
Fields inherited from class javax.swing.text.JTextComponent
DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY
 
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Constructor Summary
JNumberField()
          Constructor without input.
JNumberField(int Columns)
          Constructor with input for the length of the columns.
 
Method Summary
 double atof(java.lang.String s)
           Converts a string of digits to a double
 void caretUpdate(javax.swing.event.CaretEvent evtCaret)
          Handle the caret update event from the text field.
 void errorInput(java.awt.event.KeyEvent evtKey)
           Handle an invalid input and gives a beep
 void focusGained(java.awt.event.FocusEvent evtFocus)
          Handle the focus Gained event from the text field.
 void focusLost(java.awt.event.FocusEvent evtFocus)
          Handle the focus Lost event from the text field.
 double getDoubleValue()
           Returns a double from the JNumberField
 boolean isFieldEmpty()
           Checks whether the field is empty
 void keyPressed(java.awt.event.KeyEvent evtKey)
          Handle the key pressed event from the text field.
 void keyReleased(java.awt.event.KeyEvent evtKey)
          Handle the key released event from the text field.
 void keyTyped(java.awt.event.KeyEvent evtKey)
          Handle the key typed event from the text field.
 void noValidField()
           Method for an invalid field, gives a beep
 void resetParameters()
           Reset all paramaters for validity checking
 
Methods inherited from class javax.swing.JTextField
addActionListener, createDefaultModel, fireActionPerformed, getAccessibleContext, getActions, getColumns, getColumnWidth, getHorizontalAlignment, getHorizontalVisibility, getPreferredSize, getScrollOffset, getUIClassID, isValidateRoot, paramString, postActionEvent, removeActionListener, scrollRectToVisible, setActionCommand, setColumns, setFont, setHorizontalAlignment, setScrollOffset
 
Methods inherited from class javax.swing.text.JTextComponent
addCaretListener, addKeymap, copy, cut, fireCaretUpdate, getCaret, getCaretColor, getCaretPosition, getDisabledTextColor, getDocument, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getPreferredScrollableViewportSize, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getText, getUI, isEditable, isFocusTraversable, isOpaque, loadKeymap, modelToView, moveCaretPosition, paste, processComponentKeyEvent, processInputMethodEvent, read, removeCaretListener, removeKeymap, removeNotify, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setDisabledTextColor, setDocument, setEditable, setEnabled, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setOpaque, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, write
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getAlignmentX, getAlignmentY, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getGraphics, getHeight, getInsets, getInsets, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getVisibleRect, getWidth, getX, getY, grabFocus, hasFocus, isDoubleBuffered, isFocusCycleRoot, isLightweightComponent, isManagingFocus, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, processFocusEvent, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, resetKeyboardActions, reshape, revalidate, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDoubleBuffered, setForeground, setMaximumSize, setMinimumSize, setNextFocusableComponent, setPreferredSize, setRequestFocusEnabled, setToolTipText, setUI, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getLayout, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setLayout, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addPropertyChangeListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getInputContext, getLocale, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hide, imageUpdate, inside, isDisplayable, isEnabled, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processMouseEvent, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

JNumberField

public JNumberField(int Columns)
Constructor with input for the length of the columns.

JNumberField

public JNumberField()
Constructor without input.
Method Detail

keyTyped

public void keyTyped(java.awt.event.KeyEvent evtKey)
Handle the key typed event from the text field.
Specified by:
keyTyped in interface java.awt.event.KeyListener

keyPressed

public void keyPressed(java.awt.event.KeyEvent evtKey)
Handle the key pressed event from the text field.
Specified by:
keyPressed in interface java.awt.event.KeyListener

keyReleased

public void keyReleased(java.awt.event.KeyEvent evtKey)
Handle the key released event from the text field.
Specified by:
keyReleased in interface java.awt.event.KeyListener

caretUpdate

public void caretUpdate(javax.swing.event.CaretEvent evtCaret)
Handle the caret update event from the text field.
Specified by:
caretUpdate in interface javax.swing.event.CaretListener

focusGained

public void focusGained(java.awt.event.FocusEvent evtFocus)
Handle the focus Gained event from the text field.
Specified by:
focusGained in interface java.awt.event.FocusListener

focusLost

public void focusLost(java.awt.event.FocusEvent evtFocus)
Handle the focus Lost event from the text field.
Specified by:
focusLost in interface java.awt.event.FocusListener

getDoubleValue

public double getDoubleValue()
Most important method of JNumberField: returns a double from the JNumberField

atof

public double atof(java.lang.String s)
Converts a string of digits to a double

isFieldEmpty

public boolean isFieldEmpty()
Checks whether the field is empty

errorInput

public void errorInput(java.awt.event.KeyEvent evtKey)
Handle an invalid input and gives a beep

noValidField

public void noValidField()
Method for an invalid field, gives a beep

resetParameters

public void resetParameters()
Reset all paramaters for validity checking





Computer Chemistry Consultancy, June 2001
Contact us at compchemcons@hotmail.com