Document multiple load semantics in @StyleSheet and @JavaScript (#12200)

Change-Id: Id52f196ad6d14e8077482b19a8d0479aedc64db3

2 files changed, 26 insertions, 2 deletions

diff --git a/server/src/com/vaadin/annotations/JavaScript.java b/server/src/com/vaadin/annotations/JavaScript.java
index f2085556c7..bdba70c095 100644
--- a/server/src/com/vaadin/annotations/JavaScript.java
+++ b/server/src/com/vaadin/annotations/JavaScript.java
@@ -29,9 +29,21 @@ import com.vaadin.server.ClientConnector;
  * method for the corresponding client-side connector is invoked.
  * <p>
  * Absolute URLs including protocol and host are used as is on the client-side.
- * Relative urls are mapped to APP/PUBLISHED/[url] which are by default served
+ * Relative URLs are mapped to APP/PUBLISHED/[url] which are by default served
  * from the classpath relative to the class where the annotation is defined.
  * <p>
+ * The file is only loaded if it has not already been loaded, determined as
+ * follows:
+ * <ul>
+ * <li>For absolute URLs, the URL is considered loaded if the same URL has
+ * previously been loaded using {@code @JavaScript} or if a script tag loaded
+ * from the same URL was present in the DOM when the Vaadin client-side was
+ * initialized.
+ * <li>For relative URLs, the URL is considered loaded if another file with the
+ * same name has already been loaded using {@code @JavaScript}, even if that
+ * file was loaded from a different folder.
+ * </ul>
+ * <p>
  * Example: {@code @JavaScript( "http://host.com/file1.js", "file2.js"})} on the
  * class com.example.MyConnector would load the file http://host.com/file1.js as
  * is and file2.js from /com/example/file2.js on the server's classpath using
diff --git a/server/src/com/vaadin/annotations/StyleSheet.java b/server/src/com/vaadin/annotations/StyleSheet.java
index 2e15d9481c..6540633f8f 100644
--- a/server/src/com/vaadin/annotations/StyleSheet.java
+++ b/server/src/com/vaadin/annotations/StyleSheet.java
@@ -29,9 +29,21 @@ import com.vaadin.server.ClientConnector;
  * method for the corresponding client-side connector is invoked.
  * <p>
  * Absolute URLs including protocol and host are used as is on the client-side.
- * Relative urls are mapped to APP/PUBLISHED/[url] which are by default served
+ * Relative URLs are mapped to APP/PUBLISHED/[url] which are by default served
  * from the classpath relative to the class where the annotation is defined.
  * <p>
+ * The file is only loaded if it has not already been loaded, determined as
+ * follows:
+ * <ul>
+ * <li>For absolute URLs, the URL is considered loaded if the same URL has
+ * previously been loaded using {@code StyleSheet} or if a
+ * {@code <link rel="stylesheet">} tag using the same URL was present in the DOM
+ * when the Vaadin client-side was initialized.
+ * <li>For relative URLs, the URL is considered loaded if another file with the
+ * same name has already been loaded using {@code StyleSheet}, even if that file
+ * was loaded from a different folder.
+ * </ul>
+ * <p>
  * Special Vaadin urls are also supported. The most useful is vaadin:// which
  * maps to the location of the automatically published VAADIN folder. Using the
  * VAADIN folder and vaadin:// you can publish stylesheets which use images or