You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sebb <se...@gmail.com> on 2011/05/04 14:10:16 UTC
Re: svn commit: r1099416 - /commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/text/FormattableUtils.java
On 4 May 2011 12:22, <sc...@apache.org> wrote:
> Author: scolebourne
> Date: Wed May 4 11:22:29 2011
> New Revision: 1099416
>
> URL: http://svn.apache.org/viewvc?rev=1099416&view=rev
> Log:
> Javadoc
>
> Modified:
> commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/text/FormattableUtils.java
>
> Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/text/FormattableUtils.java
> URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/text/FormattableUtils.java?rev=1099416&r1=1099415&r2=1099416&view=diff
> ==============================================================================
> --- commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/text/FormattableUtils.java (original)
> +++ commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/text/FormattableUtils.java Wed May 4 11:22:29 2011
> @@ -26,17 +26,24 @@ import org.apache.commons.lang3.StringUt
> import org.apache.commons.lang3.Validate;
>
> /**
> - * Provides utilities for working with {@link Formattable}s.
> + * <p>Provides utilities for working with the {@code Formattable} interface.</p>
> + *
> + * <p>The {@link Formattable} interface provides basic control over formatting
> + * when using a {@code Formatter}. It is primarily concerned with numeric precision
> + * and padding, and is not designed to allow generalised alternate formats.</p>
> *
> * @since Lang 3.0
> * @version $Id$
> */
> public class FormattableUtils {
>
> + /**
> + * A format that simply outputs the value as a string.
> + */
> private static final String SIMPLEST_FORMAT = "%s";
>
> /**
> - * <p>{@link FormattableUtils} instances should NOT be constructed in
> + * <p>{@code FormattableUtils} instances should NOT be constructed in
What's wrong with @link here?
> * standard programming. Instead, the methods of the class should be invoked
> * statically.</p>
> *
> @@ -47,28 +54,29 @@ public class FormattableUtils {
> super();
> }
>
> + //-----------------------------------------------------------------------
> /**
> * Get the default formatted representation of the specified
> - * {@link Formattable}.
> + * {@code Formattable}.
Ditto
> *
> - * @param formattable to convert to a String
> - * @return String
> + * @param formattable the instance to convert to a string, not null
> + * @return the resulting string, not null
> */
> public static String toString(Formattable formattable) {
> return String.format(SIMPLEST_FORMAT, formattable);
> }
>
> /**
> - * Handles the common {@link Formattable} operations of truncate-pad-append,
> + * Handles the common {@code Formattable} operations of truncate-pad-append,
> * with no ellipsis on precision overflow, and padding width underflow with
> * spaces.
> *
> - * @param seq to handle
> - * @param formatter destination
> - * @param flags for formatting
> - * @param width of output
> - * @param precision of output
> - * @return {@code formatter}
> + * @param seq the string to handle, not null
> + * @param formatter the destination formatter, not null
> + * @param flags the flags for formatting, see {@code Formattable}
> + * @param width the width of the output, see {@code Formattable}
> + * @param precision the precision of the output, see {@code Formattable}
> + * @return the {@code formatter} instance, not null
> */
> public static Formatter append(CharSequence seq, Formatter formatter, int flags, int width,
> int precision) {
> @@ -79,13 +87,13 @@ public class FormattableUtils {
> * Handles the common {@link Formattable} operations of truncate-pad-append,
> * with no ellipsis on precision overflow.
> *
> - * @param seq to handle
> - * @param formatter destination
> - * @param flags for formatting
> - * @param width of output
> - * @param precision of output
> - * @param padChar to use
> - * @return {@code formatter}
> + * @param seq the string to handle, not null
> + * @param formatter the destination formatter, not null
> + * @param flags the flags for formatting, see {@code Formattable}
> + * @param width the width of the output, see {@code Formattable}
> + * @param precision the precision of the output, see {@code Formattable}
> + * @param padChar the pad character to use
> + * @return the {@code formatter} instance, not null
> */
> public static Formatter append(CharSequence seq, Formatter formatter, int flags, int width,
> int precision, char padChar) {
> @@ -96,14 +104,14 @@ public class FormattableUtils {
> * Handles the common {@link Formattable} operations of truncate-pad-append,
> * padding width underflow with spaces.
> *
> - * @param seq to handle
> - * @param formatter destination
> - * @param flags for formatting
> - * @param width of output
> - * @param precision of output
> - * @param ellipsis to use when precision dictates truncation; a {@code null}
> - * or empty value causes a hard truncation
> - * @return {@code formatter}
> + * @param seq the string to handle, not null
> + * @param formatter the destination formatter, not null
> + * @param flags the flags for formatting, see {@code Formattable}
> + * @param width the width of the output, see {@code Formattable}
> + * @param precision the precision of the output, see {@code Formattable}
> + * @param ellipsis the ellipsos to use when precision dictates truncation, null or
> + * empty causes a hard truncation
> + * @return the {@code formatter} instance, not null
> */
> public static Formatter append(CharSequence seq, Formatter formatter, int flags, int width,
> int precision, CharSequence ellipsis) {
> @@ -113,15 +121,15 @@ public class FormattableUtils {
> /**
> * Handles the common {@link Formattable} operations of truncate-pad-append.
> *
> - * @param seq to handle
> - * @param formatter destination
> - * @param flags for formatting
> - * @param width of output
> - * @param precision of output
> - * @param padChar to use
> - * @param ellipsis to use when precision dictates truncation; a {@code null}
> - * or empty value causes a hard truncation
> - * @return {@code formatter}
> + * @param seq the string to handle, not null
> + * @param formatter the destination formatter, not null
> + * @param flags the flags for formatting, see {@code Formattable}
> + * @param width the width of the output, see {@code Formattable}
> + * @param precision the precision of the output, see {@code Formattable}
> + * @param padChar the pad character to use
> + * @param ellipsis the ellipsos to use when precision dictates truncation, null or
> + * empty causes a hard truncation
> + * @return the {@code formatter} instance, not null
> */
> public static Formatter append(CharSequence seq, Formatter formatter, int flags, int width,
> int precision, char padChar, CharSequence ellipsis) {
> @@ -139,4 +147,5 @@ public class FormattableUtils {
> formatter.format(buf.toString());
> return formatter;
> }
> +
> }
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: svn commit: r1099416 - /commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/text/FormattableUtils.java
Posted by Stephen Colebourne <sc...@joda.org>.
On 4 May 2011 13:10, sebb <se...@gmail.com> wrote:
>> /**
>> - * <p>{@link FormattableUtils} instances should NOT be constructed in
>> + * <p>{@code FormattableUtils} instances should NOT be constructed in
>
> What's wrong with @link here?
In general, it is not advisable to use @link in the first sentence of
a Javadoc class or method description. That is because it appears
linked in the summary documentation:
http://people.apache.org/~bayard/commons-lang3-3.0-RC3/site/apidocs/org/apache/commons/lang3/text/package-summary.html
http://people.apache.org/~bayard/commons-lang3-3.0-RC3/site/apidocs/org/apache/commons/lang3/text/FormattableUtils.html
These links (especially at the class level) are distracting when
viewing that summary.
Thus, it is better to use @code in the first sentence, and @link for
the main description if necessary (but only for the first link in any
doc). More generally, I would say that @link is a slightly over-used,
as there is frequently a link available via a method signature anyway
(not relevant in this case).
I'd also note that Oracle has recently had a mail recommending that
null, true and false are NOT surrounded by @code (for readbility).
Stephen
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org