Better comments

Also introduces a new format of file opening comment, to outline what happens and a contents list.

core/client/assets/sass/modules/icons.scss

@@ -1,6 +1,26 @@
+// ------------------------------------------------------------
+// Icons
 //
-// Pictos, by Drew Wilson - http://pictos.cc/
+// Defined the @font-face rule for the icon font, as well as
+// the base styles for when using icons.
+// Includes the mixins for adding icons directly and the
+// variables for each icon.
+//
+// * Font-face rule
+// * Base styled for icons
+// * Base styled for icons
+// * The Icon (before) Mixin
+// * The Icon (after) Mixin
+// * Icon Variables
+// * Icon Class Styles
+// * Icon Classes
+// ------------------------------------------------------------
+
+
+//
+// Font-face rule
 // Icon-font is generated by http://icomoon.co
+// Pictos, by Drew Wilson - http://pictos.cc/
 // --------------------------------------------------
 
 @font-face {
@@ -15,9 +35,8 @@
 }
 
 
-
 //
-// The Icon (before) Mixin
+// Base styled for icons
 // --------------------------------------------------
 
 %icon-base {
@@ -85,8 +104,7 @@
 // --------------------------------------------------
 // For accessibility, icon characters in the icon font are stored in Unicode's
 // Private Use Area characters. This means that screen readers won't attempt to
-// read them out loud. For code maintainability, we then store these Unicode
-// references inside Sass variables.
+// read them out loud.
 //
 
 // Placeholder

core/client/assets/sass/modules/mixins.scss

@@ -1,15 +1,29 @@
-//
+// ------------------------------------------------------------
 // Mixins
+//
+// Mixins defined here are very general and used in mul
+//
+// * baseline()
+// * clearfix()
+// * tab-focus()
+// * triangle()
+// * set-triangle-color()
+// ------------------------------------------------------------
+
+
+//
+// Baseline margin
 // --------------------------------------------------
 
-
-// Baseline margin
 @mixin baseline {
     margin: 1.6em 0;
 }
 
 
+//
 // Fix for clearing float-based overflows
+// --------------------------------------------------
+
 @mixin clearfix {
     &:after {
         content: "";
@@ -19,8 +33,10 @@
 }
 
 
+//
 // WebKit-style focus
 // From Bootstrap
+// --------------------------------------------------
 @mixin tab-focus() {
     // Default
     outline: thin dotted;
@@ -30,8 +46,11 @@
 }
 
 
+//
 // Simple SCSS mixin to create CSS triangles
 // Example: @include css-triangle (10px, #fff, "up");
+// --------------------------------------------------
+
 @mixin triangle($size: 20px, $color: #000, $direction: "down", $type: "normal") {
     $verticalSize: $size;
     width: 0;
@@ -42,33 +61,36 @@
     }
 
     @if $direction == "down" {
-        border-left: $size solid #{setTriangleColor($direction, "left", $color)};
-        border-right: $size solid #{setTriangleColor($direction, "right", $color)};
-        border-top: $verticalSize solid #{setTriangleColor($direction, "top", $color)};
+        border-left: $size solid #{set-triangle-color($direction, "left", $color)};
+        border-right: $size solid #{set-triangle-color($direction, "right", $color)};
+        border-top: $verticalSize solid #{set-triangle-color($direction, "top", $color)};
     }
 
     @if $direction == "up" {
-        border-left: $size solid #{setTriangleColor($direction, "left", $color)};
-        border-right: $size solid #{setTriangleColor($direction, "right", $color)};
-        border-bottom: $verticalSize solid #{setTriangleColor($direction, "bottom", $color)};
+        border-left: $size solid #{set-triangle-color($direction, "left", $color)};
+        border-right: $size solid #{set-triangle-color($direction, "right", $color)};
+        border-bottom: $verticalSize solid #{set-triangle-color($direction, "bottom", $color)};
     }
 
     @if $direction == "left" {
-        border-right: $verticalSize solid #{setTriangleColor($direction, "right", $color)};
-        border-top: $size solid #{setTriangleColor($direction, "top", $color)};
-        border-bottom: $size solid #{setTriangleColor($direction, "bottom", $color)};
+        border-right: $verticalSize solid #{set-triangle-color($direction, "right", $color)};
+        border-top: $size solid #{set-triangle-color($direction, "top", $color)};
+        border-bottom: $size solid #{set-triangle-color($direction, "bottom", $color)};
     }
 
     @if $direction == "right" {
-        border-left: $verticalSize solid #{setTriangleColor($direction, "left", $color)};
-        border-bottom: $size solid #{setTriangleColor($direction, "bottom", $color)};
-        border-top: $size solid #{setTriangleColor($direction, "top", $color)};
+        border-left: $verticalSize solid #{set-triangle-color($direction, "left", $color)};
+        border-bottom: $size solid #{set-triangle-color($direction, "bottom", $color)};
+        border-top: $size solid #{set-triangle-color($direction, "top", $color)};
     }
 }
 
 
+//
 // Utility function to return the relevant colour depending on what type of arrow it is
-@function setTriangleColor($direction, $side, $color) {
+// --------------------------------------------------
+
+@function set-triangle-color($direction, $side, $color) {
     @if $direction == "left" and $side == "right"
     or  $direction == "right" and $side == "left"
     or $direction == "down" and $side == "top"

core/client/assets/sass/modules/variables.scss

@@ -7,7 +7,10 @@
 // ------------------------------------------------------------
 
 
+//
 // Colours
+// --------------------------------------------------
+
 $darkgrey: #242628;
 $grey: #35393b;
 $midgrey: #7d878a;
@@ -22,6 +25,7 @@ $orange: #F2A925;
 $green: #9FBB58;
 
 
+//
 // Default style values
 // --------------------------------------------------
 
@@ -33,7 +37,10 @@ $font-family: 'Open Sans', sans-serif;
 $font-family-mono: monospace;
 
 
+//
 // Dropdown & Popover triangles
+// --------------------------------------------------
+
 $dropdown_triangle: 8px;
 $popover_triangle: 14px;
 $popover_triangle_shallow_multiplier: 0.8; // Adjusts the height of the triangle relative to its width, so it's 0.8x the height of the width