From b6d785312a8e5679cb9fe41a90b522250a48698d Mon Sep 17 00:00:00 2001
From: Artur Signell <artur@vaadin.com>
Date: Mon, 12 Dec 2011 13:23:32 +0200
Subject: #8101 Javadoc for Converter

---
 src/com/vaadin/data/util/converter/Converter.java | 84 ++++++++++++++++++++++-
 1 file changed, 82 insertions(+), 2 deletions(-)

diff --git a/src/com/vaadin/data/util/converter/Converter.java b/src/com/vaadin/data/util/converter/Converter.java
index 3d21cc36f7..24107c241e 100644
--- a/src/com/vaadin/data/util/converter/Converter.java
+++ b/src/com/vaadin/data/util/converter/Converter.java
@@ -7,21 +7,101 @@ package com.vaadin.data.util.converter;
 import java.io.Serializable;
 import java.util.Locale;
 
+/**
+ * Interface that implements conversion between objects of one type to another
+ * and back.
+ * <p>
+ * Typically {@link #convertFromSourceToTarget(Object, Locale)} and
+ * {@link #convertFromTargetToSource(Object, Locale)} should be symmetric so
+ * that chaining these together returns the original result for all input but
+ * this is not a requirement.
+ * </p>
+ * <p>
+ * Converters must not have any side effects (never update UI from inside a
+ * converter).
+ * </p>
+ * <p>
+ * If conversion of a value fails, a {@link ConversionException} is thrown.
+ * </p>
+ * 
+ * @param <SOURCE>
+ * @param <TARGET>
+ * @author Vaadin Ltd.
+ * @version
+ * @VERSION@
+ * @since 7.0
+ */
 public interface Converter<SOURCE, TARGET> extends Serializable {
 
+    /**
+     * Converts the given value from target type to source type.
+     * <p>
+     * A converter can optionally use locale to do the conversion.
+     * </p>
+     * A converter should in most cases be symmetric so chaining
+     * {@link #convertFromSourceToTarget(Object, Locale)} and
+     * {@link #convertFromTargetToSource(Object, Locale)} should return the
+     * original value.
+     * 
+     * @param value
+     *            The value to convert, compatible with the target type. Can be
+     *            null
+     * @param locale
+     *            The locale to use for conversion. Can be null.
+     * @return The converted value compatible with the source type
+     * @throws ConversionException
+     *             If the value could not be converted
+     */
     public SOURCE convertFromTargetToSource(TARGET value, Locale locale)
             throws ConversionException;
 
+    /**
+     * Converts the given value from source type to target type.
+     * <p>
+     * A converter can optionally use locale to do the conversion.
+     * </p>
+     * A converter should in most cases be symmetric so chaining
+     * {@link #convertFromSourceToTarget(Object, Locale)} and
+     * {@link #convertFromTargetToSource(Object, Locale)} should return the
+     * original value.
+     * 
+     * @param value
+     *            The value to convert, compatible with the target type. Can be
+     *            null
+     * @param locale
+     *            The locale to use for conversion. Can be null.
+     * @return The converted value compatible with the source type
+     * @throws ConversionException
+     *             If the value could not be converted
+     */
     public TARGET convertFromSourceToTarget(SOURCE value, Locale locale)
             throws ConversionException;
 
+    /**
+     * The source type of the converter.
+     * 
+     * Values of this type can be passed to
+     * {@link #convertFromSourceToTarget(Object, Locale)}.
+     * 
+     * @return The source type
+     */
     public Class<SOURCE> getSourceType();
 
+    /**
+     * The target type of the converter.
+     * 
+     * Values of this type can be passed to
+     * {@link #convertFromTargetToSource(Object, Locale)}.
+     * 
+     * @return The target type
+     */
     public Class<TARGET> getTargetType();
 
     /**
-     * An exception that signals that the value passed to #convert or
-     * Converter.convertFromTargetToSource could not be converted.
+     * An exception that signals that the value passed to
+     * {@link Converter#convertFromSourceToTarget(Object, Locale)} or
+     * {@link Converter#convertFromTargetToSource(Object, Locale)} could not be
+     * converted.
      * 
      * @author Vaadin Ltd
      * @version
-- 
cgit v1.2.3