[Fmt-*] Clarify DecimalFormat description of FieldPosition use

Summary

Clarify handling of the FieldPosition settings in the java.text.Format APIs.

Problem

The java.text.Format subclasses, such as DecimalFormat, typically explains the FieldPosition argument as follows.

public final StringBuffer format(Object number, StringBuffer toAppendTo, FieldPosition pos)

pos - On input: an alignment field, if desired. On output: the offsets of the alignment field.

This description appears to be confusing. The developers may think that 'pos' can take the offset values specifying the position where the formatted text of the given field should be stored. But in actual, 'pos' is used only for getting information of the position where the formatted text of the given field has actually been stored.

In addition to this argument description problem, the format method tends to miss @return descriptions. And some just say "Formats a time object to a time string", which should mention that the formatted string is appended to the given StringBuffer.

Solution

Clarify the FieldPosition argument description of the format method in Format, DecimalFormat, MessageFormat, DateFormat, and SimpleDateFormat, if applicable.

Add any missing @return descriptions to the method.

Clarify method descriptions, such as the append-to-StringBuffer operation.

Specification

Specdiff: http://cr.openjdk.java.net/~nishjain/6354947/specdiff/specdiff.02/overview-summary.html