From 5ed9d2639ae85fe3ac0404208576fc324ce0db94 Mon Sep 17 00:00:00 2001
From: Artur Signell <artur.signell@itmill.com>
Date: Mon, 20 Sep 2010 13:36:49 +0000
Subject: [PATCH] Javadoc

svn changeset:15072/svn branch:6.4
---
 .../terminal/gwt/client/ui/SubPartAware.java  | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/src/com/vaadin/terminal/gwt/client/ui/SubPartAware.java b/src/com/vaadin/terminal/gwt/client/ui/SubPartAware.java
index 2a1bef71ff..55360cf01f 100644
--- a/src/com/vaadin/terminal/gwt/client/ui/SubPartAware.java
+++ b/src/com/vaadin/terminal/gwt/client/ui/SubPartAware.java
@@ -4,11 +4,47 @@
 package com.vaadin.terminal.gwt.client.ui;
 
 import com.google.gwt.user.client.Element;
+import com.vaadin.terminal.gwt.client.ComponentLocator;
+import com.vaadin.terminal.gwt.client.Paintable;
 
+/**
+ * Interface implemented by {@link Paintable}s which can provide identifiers for
+ * at least one element inside the component. Used by {@link ComponentLocator}.
+ * 
+ */
 public interface SubPartAware {
 
+    /**
+     * Locates an element inside a component using the identifier provided in
+     * {@code subPart}. The {@code subPart} identifier is component specific and
+     * may be any string of characters, numbers, space characters and brackets.
+     * 
+     * @param subPart
+     *            The identifier for the element inside the component
+     * @return The element identified by subPart or null if the element could
+     *         not be found.
+     */
     Element getSubPartElement(String subPart);
 
+    /**
+     * Provides an identifier that identifies the element within the component.
+     * The {@code subElement} is a part of the component and must never be null.
+     * <p>
+     * <b>Note!</b>
+     * {@code getSubPartElement(getSubPartName(element)) == element} is <i>not
+     * always</i> true. A component can choose to provide a more generic
+     * identifier for any given element if the results of all interactions with
+     * {@code subElement} are the same as interactions with the element
+     * identified by the return value. For example a button can return an
+     * identifier for the root element even though a DIV inside the button was
+     * passed as {@code subElement} because interactions with the DIV and the
+     * root button element produce the same result.
+     * 
+     * @param subElement
+     *            The element the identifier string should uniquely identify
+     * @return An identifier that uniquely identifies {@code subElement} or null
+     *         if no identifier could be provided.
+     */
     String getSubPartName(Element subElement);
 
 }
\ No newline at end of file
-- 
2.39.5