«

What is the tersest way to document a toString style method.

I would like to say something like this:

"displays" the width and height in both metric and imperial measure

But it does not display anything, just prepares for display.

I have seen people also use misleading terms like "show" and "print".

What do you use?

The best I can come up with is "format". Sun uses this is the
SimpleDateFormat class.

To me, "format" implies some sort of complicated masks or a choice of
layouts.

"prepare" is too vague.

Perhaps a phase "convert x to a string"

--

Roedy Green Canadian Mind Products
The Java Glossary
http://mindprod.com

Roedy Green wrote:

> What is the tersest way to document a toString style method.
>
> I would like to say something like this:
>
> "displays" the width and height in both metric and imperial measure
>
> But it does not display anything, just prepares for display.
>
> I have seen people also use misleading terms like "show" and "print".
>
> What do you use?
>
> The best I can come up with is "format". Sun uses this is the
> SimpleDateFormat class.
>
> To me, "format" implies some sort of complicated masks or a choice of
> layouts.
>
> "prepare" is too vague.
>
> Perhaps a phase "convert x to a string"
>

Is there anything wrong with what Object.toString() says?

"Returns a string representation of the object. "
...
"The toString method for class Object returns a string consisting of..."

Seems to do pretty much cover it.

--
Nigel Wade

On Thu, 31 Jul 2008, Eric Sosman wrote:

> Roedy Green wrote:
>
>> Perhaps a phase "convert x to a string"
>
> I've seen "stringize" used as a verb, but I don't like it much.
> Besides, speakers of Q.E. will want to spell it "stringise" and there'll
> be no end of fruitless debatez.

I've come across 'stringify', which i think is much better than
'stringize', but still probably unnecessary jargon.

tom

--
roger and kay payne, symmetry, piercing, archaeology, position, in ,,

Roedy Green wrote:
> What is the tersest way to document a toString style method.
>
> I would like to say something like this:
>
> "displays" the width and height in both metric and imperial measure
>
> But it does not display anything, just prepares for display.
>
> I have seen people also use misleading terms like "show" and "print".
>
> What do you use?
>
> The best I can come up with is "format". Sun uses this is the
> SimpleDateFormat class.
>
> To me, "format" implies some sort of complicated masks or a choice of
> layouts.
>
> "prepare" is too vague.
>
> Perhaps a phase "convert x to a string"
>

"Returns a String describing ..."
"Returns a description of ..."
"Describes ..."

--
RGB

Roedy Green wrote:
> What is the tersest way to document a toString style method.
>
> I would like to say something like this:
>
> "displays" the width and height in both metric and imperial measure
>
> But it does not display anything, just prepares for display.
>
> I have seen people also use misleading terms like "show" and "print".
>
> What do you use?
>
> The best I can come up with is "format". Sun uses this is the
> SimpleDateFormat class.
>
> To me, "format" implies some sort of complicated masks or a choice of
> layouts.
>
> "prepare" is too vague.
>
> Perhaps a phase "convert x to a string"
>
/**
* Returns a String representation of this object.
* ${detailsOfStringFormatIfApplicable}
* ${warningAboutDetailsChangingInFutureIfApplicable}
* @returns a String suitable for (debugging, parsing, sending, etc...)
*/

--
Daniel Pitts' Tech Blog: <http://virtualinfinity.net/wordpress/>

Roedy Green <> writes:
>"displays" the width and height in both metric and imperial measure

»o.toString()« "designates", "denotes", "gives",
"expresses" a string, or "evaluates to" a string.

(I do not use »returns« here, because an expression does not
»return« its value. »2« does not »return« 2, it designates 2.
I use »return« only when I want to take the point of view of
the /implementation/ of a method. It is the view from /inside/
a method that can use »return«.)

On Thu, 31 Jul 2008 13:29:51 +0200, Andrea Francia
<èdatogliereohoho ho.it> wrote, quoted
or indirectly quoted someone who said :

>The verb is "Returns a string"

It is a little verbose.

You can't use it as a verb in other contexts. e.g.

// convert the co-ordinates to String format for display.

It would be nice to abbreviate that to something like

// format the co-ordinates
// express the co-ordinates
// present the co-ordinates
// exhibit the co-ordinates
// render the co-ordinates
// flatten the co-ordinates

It might be best to pick a fairly obscure word that has no attendant
ambiguous meanings.

Two related problems:

1. What if you have several toString-style methods. e.g.
toISODateSTring toLocalisedDateString. Should those be called
formatISODate or formatAsISODate? I am a stickler for consistency.


2. How do you do the Javadoc to avoid redundancy
and potential inconsistency. e.g.

/** returns date converted to an ISO date String of the form
YYYY-MM-DD in local time.
@param theDate date you want to display.
@return the date converted to an ISO date String of the form
YYYY-MM-DD
*/

--

Roedy Green Canadian Mind Products
The Java Glossary
http://mindprod.com

Roedy Green <> writes:
>2. How do you do the Javadoc to avoid redundancy
>and potential inconsistency. e.g.
>/** returns date converted to an ISO date String of the form
>YYYY-MM-DD in local time.
>@param theDate date you want to display.
>@return the date converted to an ISO date String of the form
>YYYY-MM-DD
>*/

The repetition of »date converted to an ISO date String of the
form YYYY-MM-DD« in this case is endorsed by the style guidelines:

»The @return tag is required for every method that returns
something other than void, even if it is redundant with
the method description. (Whenever possible, find something
non-redundant (ideally, more specific) to use for the tag
comment.)«

http://java.sun.com/j2se/javadoc/writingdoccomments/

Inconsistency is avoided by attention of the author/editor,
a cut-and-paste-habbit, or a preprocessor:

$define VALUE the date converted to an ISO date String
/** Returns $VALUE.
@param theDate date to display
@return $VALUE */

There should not be a period after »date you want to display«:

»End the phrase with a period only if another phrase or
sentence follows it.

Example:

* @param ch the character to be tested«

http://java.sun.com/j2se/javadoc/writingdoccomments/

All the documentation comments for methods in this source
»writingdoccomments« start with upper case letters.
So it should probably be »/** Returns« (not »/** returns«).

Roedy Green wrote:
> What is the tersest way to document a toString style method.
>
> I would like to say something like this:
>
> "displays" the width and height in both metric and imperial measure
>
> But it does not display anything, just prepares for display.
>
> I have seen people also use misleading terms like "show" and "print".

stream (as in stream to disc)

write (as in write to a printer)

encode (as in to a specific character set)

getString, getAsString

enstring (like enclose or encapsulate)

render (I think this got mentioned)

Serialize ... don't forget you can write objects to an internal buffer
using StringWriter... maybe you should be using the API more rather than
rolling your own methods. Make a print( OutputStream o ) method, then
just hand it a StringWriter if you don't really want it to go anywhere.

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