1 files changed, 45 insertions, 13 deletions

diff --git a/WebContent/VAADIN/themes/valo/shared/_global.scss b/WebContent/VAADIN/themes/valo/shared/_global.scss
index 5c010c128d..049518af73 100644
--- a/WebContent/VAADIN/themes/valo/shared/_global.scss
+++ b/WebContent/VAADIN/themes/valo/shared/_global.scss
@@ -4,9 +4,22 @@
 @import "tooltip";
 
 
-// Include global styles only once
+/*
+ * A flag which is set to true when the global styles have been included in the compilation.
+ * Used to only include them once, if Valo is imported multiple times during the compilation
+ * (multiple theme support).
+ *
+ * @access private
+ * @type bool
+ */
 $valo-global-included: false !default;
 
+/*
+ * Global Valo related styles, containing styles which are necessary for the application
+ * and widgets to work correctly.
+ *
+ * @access private
+ */
 @mixin valo-global {
   @if $valo-global-included == false {
 
@@ -173,14 +186,16 @@ $valo-global-included: false !default;
 }
 
 
-
 $valo-shared-pathPrefix: null;
 
 @if $v-relative-paths == false {
   $valo-shared-pathPrefix: "../valo/shared/";
 }
 
-
+/**
+ * Styles for the application root element. Outputs font, font color, background color and default
+ * cursor styles.
+ */
 @mixin valo-app-style {
   font: $v-font-weight #{$v-font-size}/#{$v-line-height} $v-font-family;
   color: $v-font-color;
@@ -195,7 +210,13 @@ $valo-shared-pathPrefix: null;
   }
 }
 
-
+/**
+ * Common application styles, such as loading indicators, tooltip and context menu styles,
+ * caption and icon defaults, basic HTML element resets.
+ * Should only be included once (done automatically when including the main valo mixin).
+ *
+ * @requires {mixin} valo-app-style
+ */
 @mixin valo-common {
 
   //@if & != null {
@@ -351,7 +372,9 @@ $valo-shared-pathPrefix: null;
 
 
 
-
+/**
+ * Generic component caption styles (captions which are generated by layouts).
+ */
 @mixin valo-caption-style {
   font-size: $v-caption-font-size;
   font-weight: $v-caption-font-weight;
@@ -362,7 +385,11 @@ $valo-shared-pathPrefix: null;
 }
 
 
-
+/**
+ * Error indicator styles. The error indicator is by default a font character which you can style freely.
+ *
+ * @requires {mixin} valo-error-indicator-icon-style by default
+ */
 @mixin valo-error-indicator-style {
   color: $v-error-indicator-color;
   font-weight: 600;
@@ -374,18 +401,23 @@ $valo-shared-pathPrefix: null;
   }
 }
 
+/**
+ * The error indicator icon style. Should be a font character or a font icon.
+ */
 @mixin valo-error-indicator-icon-style {
   content: "!";
 }
 
 
-
-// Make the BODY element scrollable instead of the .v-ui element. Scrolling the BODY works better on touch screens.
-// NOTE: breaks percentage sized overlay elements
-// @mixin valo-natural-page-scrolling
-// @usage
-// // Call without any parent selector somewhere in your theme
-// =valo-natural-page-scrolling;
+/**
+ * Make the BODY element scrollable instead of the .v-ui element. Scrolling the BODY usually
+ * works better on touch devices. You loose the ability to control the scroll position from
+ * the server side when using this.
+ *
+ * @example scss
+ *  // Include without any parent selector
+ *  @include valo-natural-page-scrolling;
+ */
 @mixin valo-natural-page-scrolling {
 
   html {