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:

Class 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
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
Fields inherited from class javax.swing.JTextField
Fields inherited from class javax.swing.text.JTextComponent
Fields inherited from class javax.swing.JComponent
Fields inherited from class java.awt.Component
Constructor Summary
          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


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


public JNumberField()
Constructor without input.
Method Detail


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


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


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


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


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


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


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


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


public boolean isFieldEmpty()
Checks whether the field is empty


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


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


public void resetParameters()
Reset all paramaters for validity checking

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