Re: Terminolgy: the verb corresponding to "toString"
Andrea Francia wrote:
How do you would write a Javadoc comment for a method like that?
How do you write the Javadoc comments for the setter and the getter
methods?
I think Lew is saying there is no formula or specification. It's an ad
hoc process, part black art. Toward that end, here's some example from
Sun's Java docs:
getColumns
public int getColumns()
Returns the number of columns in this TextField.
Returns:
the number of columns >= 0
((It's important to remember that the first sentence will appear in the
summary at the top of a class's Java doc page.))
getColumnWidth
protected int getColumnWidth()
Returns the column width. The meaning of what a column is can be
considered a fairly weak notion for some fonts. This method is used to
define the width of a column. By default this is defined to be the width
of the character m for the font used. This method can be redefined to be
some alternative amount
Returns:
the column width >= 1
getPreferredSize
public Dimension getPreferredSize()
Returns the preferred size Dimensions needed for this TextField. If
a non-zero number of columns has been set, the width is set to the
columns multiplied by the column width.
Overrides:
getPreferredSize in class JComponent
Returns:
the dimension of this textfield
See Also:
JComponent.setPreferredSize(java.awt.Dimension), ComponentUI
((Notice that the main text portion tends to be in a more
conversational, informal style, whereas the @Returns portion attempts to
set some formal invariants on the return type. Notice also that the
last quote above seems to break this by not really saying anything about
the range of the Dimension object returned. Possibly this is because
describing the range of return values for a Dimension would be verbose,
and Sun feels the @Return comment should be brief.))
setColumns
public void setColumns(int columns)
Sets the number of columns in this TextField, and then invalidate
the layout.
Parameters:
columns - the number of columns >= 0
Throws:
IllegalArgumentException - if columns is less than 0
((Notice here how the return invariant of getColumns, and the parameter
required invariant match up with setColumns.))
getColumnWidth
protected int getColumnWidth()
Returns the column width. The meaning of what a column is can be
considered a fairly weak notion for some fonts. This method is used to
define the width of a column. By default this is defined to be the width
of the character m for the font used. This method can be redefined to be
some alternative amount
Returns:
the column width >= 1
((There is no setPreferredSize method for this class, it inherits from
JComponent.))
setPreferredSize
public void setPreferredSize(Dimension preferredSize)
Sets the preferred size of this component. If preferredSize is
null, the UI will be asked for the preferred size.
Overrides:
setPreferredSize in class Component
Parameters:
preferredSize - The new preferred size, or null
See Also:
Component.getPreferredSize(), Component.isPreferredSizeSet()
((Possibly the specified interaction with the rest of the UI is why they
don't specify much about the invariants on a Dimension return from
getPreferredSize -- it's out of the hands of the writer of the Java doc
for this class.))