chore: Improve deprecate and javadoc for StyleSheet (#22493)

* chore: Improve deprecate and javadoc for StyleSheet

* add a note about where to put the annotation

* Apply suggestion from @mcollovati

Co-authored-by: Marco Collovati <[email protected]>

* Apply suggestion from @mcollovati

Co-authored-by: Marco Collovati <[email protected]>

* Update flow-server/src/main/java/com/vaadin/flow/component/dependency/StyleSheet.java

Co-authored-by: Marco Collovati <[email protected]>

---------

Co-authored-by: Marco Collovati <[email protected]>

Author: mshabarov

flow-server/src/main/java/com/vaadin/flow/component/dependency/StyleSheet.java

@@ -28,10 +28,11 @@
 
 /**
  * Loads style sheets into the browser according to a given loading mode. Style
- * sheet URLs can be either a file served by the application itself, or an
- * external URL.
+ * sheet URLs can be either a file served by the application itself, i.e. in
+ * public static resource locations like
+ * {@code src/main/resources/META-INF/resources/}, or an external URL.
  * <p>
- * Can defines style sheet dependencies for a {@link Component} class or
+ * Can define style sheet dependencies for a {@link Component} class or
  * globally.
  * <p>
  * When this annotation is placed on the
@@ -40,6 +41,30 @@
  * during bootstrap. In this case the style sheet is always inlined in the body
  * of the html page, thus {@link LoadMode} values are ignored.
  * <p>
+ * This annotation is a recommended way to select a Vaadin theme and to import
+ * stylesheets. To be put on a class implementing
+ * {@link com.vaadin.flow.component.page.AppShellConfigurator} in this case.
+ * Example of usage:
+ * 
+ * <pre>
+ *     // theme selection
+ *     &#64;StyleSheet(Aura.STYLESHEET) // or Lumo.STYLESHEET
+ *     public class Application implements AppShellConfigurator {
+ *         ...
+ *     }
+ *
+ *     OR
+ *
+ *     &#64;StyleSheet("styles.css") // from src/main/resources/META-INF/resources/styles.css
+ *     public class Application implements AppShellConfigurator {
+ *         ...
+ *     }
+ *     // and using @import in the styles.css:
+ *
+ *     &#64;import '@vaadin/aura/aura.css';
+ *     // your custom styles ...
+ * </pre>
+ * <p>
  * For adding multiple style sheets, you can use this annotation multiple times.
  * It is guaranteed that dependencies will be loaded only once.
  * <p>

flow-server/src/main/java/com/vaadin/flow/theme/Theme.java

@@ -77,9 +77,12 @@
  * @since 1.0
  * @deprecated As of Vaadin 25, this annotation is deprecated. The theming
  *             system has been reworked to use
+ *             {@link com.vaadin.flow.component.dependency.StyleSheet} to load
+ *             one or more stylesheets from public static resources locations or
  *             {@link com.vaadin.flow.component.dependency.CssImport} to load
- *             one or more stylesheets and use mechanisms native to HTML, CSS
- *             and React (e.g. {@code @import url("morestyles.css")} in CSS).
+ *             one or more stylesheets from a {@code src/main/frontend/} folder
+ *             and use mechanisms native to HTML, CSS and React (e.g.
+ *             {@code @import url("morestyles.css")} in CSS).
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)