From f5872981ddf8ff274a12ee59d7a0116e61bde602 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Leif=20=C3=85strand?= <leif@vaadin.com>
Date: Fri, 2 Aug 2013 08:32:45 +0300
Subject: [PATCH] Improve URI fragment listener javadocs (#12296)

Change-Id: I7c91768f02d04c613f25e5984cb015067465815c
---
 server/src/com/vaadin/server/Page.java | 53 ++++++++++++++++++++++----
 1 file changed, 46 insertions(+), 7 deletions(-)

diff --git a/server/src/com/vaadin/server/Page.java b/server/src/com/vaadin/server/Page.java
index 4dd7d34e38..3656309be5 100644
--- a/server/src/com/vaadin/server/Page.java
+++ b/server/src/com/vaadin/server/Page.java
@@ -244,9 +244,23 @@ public class Page implements Serializable {
     public static final BorderStyle BORDER_DEFAULT = BorderStyle.DEFAULT;
 
     /**
-     * Listener that listens to changes in URI fragment.
+     * Listener that that gets notified when the URI fragment of the page
+     * changes.
+     * 
+     * @see Page#addUriFragmentChangedListener(UriFragmentChangedListener)
      */
     public interface UriFragmentChangedListener extends Serializable {
+        /**
+         * Event handler method invoked when the URI fragment of the page
+         * changes. Please note that the initial URI fragment has already been
+         * set when a new UI is initialized, so there will not be any initial
+         * event for listeners added during {@link UI#init(VaadinRequest)}.
+         * 
+         * @see Page#addUriFragmentChangedListener(UriFragmentChangedListener)
+         * 
+         * @param event
+         *            the URI fragment changed event
+         */
         public void uriFragmentChanged(UriFragmentChangedEvent event);
     }
 
@@ -267,12 +281,14 @@ public class Page implements Serializable {
     private List<Notification> notifications;
 
     /**
-     * Event fired when uri fragment changes.
+     * Event fired when the URI fragment of a <code>Page</code> changes.
+     * 
+     * @see Page#addUriFragmentChangedListener(UriFragmentChangedListener)
      */
     public static class UriFragmentChangedEvent extends EventObject {
 
         /**
-         * The new uri fragment
+         * The new URI fragment
          */
         private final String uriFragment;
 
@@ -281,6 +297,8 @@ public class Page implements Serializable {
          * 
          * @param source
          *            the Source of the event.
+         * @param uriFragment
+         *            the new uriFragment
          */
         public UriFragmentChangedEvent(Page source, String uriFragment) {
             super(source);
@@ -288,16 +306,16 @@ public class Page implements Serializable {
         }
 
         /**
-         * Gets the uI in which the fragment has changed.
+         * Gets the page in which the fragment has changed.
          * 
-         * @return the uI in which the fragment has changed
+         * @return the page in which the fragment has changed
          */
         public Page getPage() {
             return (Page) getSource();
         }
 
         /**
-         * Get the new fragment
+         * Get the new URI fragment
          * 
          * @return the new fragment
          */
@@ -476,6 +494,19 @@ public class Page implements Serializable {
         }
     }
 
+    /**
+     * Adds a listener that gets notified every time the URI fragment of this
+     * page is changed. Please note that the initial URI fragment has already
+     * been set when a new UI is initialized, so there will not be any initial
+     * event for listeners added during {@link UI#init(VaadinRequest)}.
+     * 
+     * @see #getUriFragment()
+     * @see #setUriFragment(String)
+     * @see #removeUriFragmentChangedListener(UriFragmentChangedListener)
+     * 
+     * @param listener
+     *            the URI fragment listener to add
+     */
     public void addUriFragmentChangedListener(
             Page.UriFragmentChangedListener listener) {
         addListener(UriFragmentChangedEvent.class, listener,
@@ -491,6 +522,14 @@ public class Page implements Serializable {
         addUriFragmentChangedListener(listener);
     }
 
+    /**
+     * Removes a URI fragment listener that was previously added to this page.
+     * 
+     * @param listener
+     *            the URI fragment listener to remove
+     * 
+     * @see Page#addUriFragmentChangedListener(UriFragmentChangedListener)
+     */
     public void removeUriFragmentChangedListener(
             Page.UriFragmentChangedListener listener) {
         removeListener(UriFragmentChangedEvent.class, listener,
@@ -520,7 +559,7 @@ public class Page implements Serializable {
      * 
      * @param newUriFragment
      *            The new fragment.
-     * @param fireEvent
+     * @param fireEvents
      *            true to fire event
      * 
      * @see #getUriFragment()
-- 
2.39.5