more comments and formatting clean up

11 files changed, 87 insertions, 52 deletions

diff --git a/scss/_input-group.scss b/scss/_input-group.scss
index ec6e385e94..c2e511aeca 100644
--- a/scss/_input-group.scss
+++ b/scss/_input-group.scss
@@ -2,8 +2,11 @@
 // Input groups
 // --------------------------------------------------
 
+
+//
 // Base styles
-// -------------------------
+//
+
 .input-group {
   position: relative; // For dropdowns
   display: table;
@@ -32,6 +35,24 @@
   }
 }
 
+.input-group-addon,
+.input-group-btn,
+.input-group .form-control {
+  display: table-cell;
+
+  &:not(:first-child):not(:last-child) {
+    @include border-radius(0);
+  }
+}
+
+.input-group-addon,
+.input-group-btn {
+  width: 1%;
+  white-space: nowrap;
+  vertical-align: middle; // Match the inputs
+}
+
+
 // Sizing options
 //
 // Remix the default form control sizing classes into new ones for easier
@@ -49,27 +70,10 @@
 }
 
 
-// Display as table-cell
-// -------------------------
-.input-group-addon,
-.input-group-btn,
-.input-group .form-control {
-  display: table-cell;
-
-  &:not(:first-child):not(:last-child) {
-    @include border-radius(0);
-  }
-}
-// Addon and addon wrapper for buttons
-.input-group-addon,
-.input-group-btn {
-  width: 1%;
-  white-space: nowrap;
-  vertical-align: middle; // Match the inputs
-}
-
+//
 // Text input groups
-// -------------------------
+//
+
 .input-group-addon {
   padding: $padding-base-vertical $padding-base-horizontal;
   font-size: $font-size-base;
@@ -100,7 +104,11 @@
   }
 }
 
+
+//
 // Reset rounded corners
+//
+
 .input-group .form-control:first-child,
 .input-group-addon:first-child,
 .input-group-btn:first-child > .btn,
@@ -126,8 +134,11 @@
   border-left: 0;
 }
 
+
+//
 // Button input groups
-// -------------------------
+//
+
 .input-group-btn {
   position: relative;
   // Jankily prevent input button groups from wrapping with `white-space` and
diff --git a/scss/_labels.scss b/scss/_labels.scss
index 5c4a29afa1..ae6ded5b2d 100644
--- a/scss/_labels.scss
+++ b/scss/_labels.scss
@@ -2,6 +2,7 @@
 // Labels
 // --------------------------------------------------
 
+
 .label {
   display: inline-block;
   padding: .25em .4em;
@@ -35,8 +36,10 @@ a.label {
   }
 }
 
+
 // Colors
-// Contextual variations (linked labels get darker on :hover)
+//
+// Contextual variations (linked labels get darker on :hover).
 
 .label-default {
   @include label-variant($label-default-bg);
diff --git a/scss/_media.scss b/scss/_media.scss
index aec4b334cb..e5eb7aba32 100644
--- a/scss/_media.scss
+++ b/scss/_media.scss
@@ -1,3 +1,7 @@
+//
+// Media
+// --------------------------------------------------
+
 .media {
   // Proper spacing between instances of .media
   margin-top: 15px;
diff --git a/scss/_modal.scss b/scss/_modal.scss
index 40b94f2938..5dd79f76ad 100644
--- a/scss/_modal.scss
+++ b/scss/_modal.scss
@@ -2,11 +2,13 @@
 // Modals
 // --------------------------------------------------
 
+
 // .modal-open      - body class for killing the scroll
 // .modal           - container to scroll within
 // .modal-dialog    - positioning shell for the actual modal
 // .modal-content   - actual modal w/ bg and corners and shit
 
+
 // Kill the scroll on the body
 .modal-open {
   overflow: hidden;
diff --git a/scss/_nav.scss b/scss/_nav.scss
index 228613cfe6..eb123b7b4c 100644
--- a/scss/_nav.scss
+++ b/scss/_nav.scss
@@ -2,6 +2,11 @@
 // Navs
 // --------------------------------------------------
 
+
+//
+// Base styles
+//
+
 .nav {
   margin-bottom: 0;
   @extend .list-unstyled;
diff --git a/scss/_pagination.scss b/scss/_pagination.scss
index 55814b94a1..01e4c3f081 100644
--- a/scss/_pagination.scss
+++ b/scss/_pagination.scss
@@ -1,6 +1,8 @@
 //
 // Pagination (multiple pages)
 // --------------------------------------------------
+
+
 .pagination {
   display: inline-block;
   padding-left: 0;
@@ -70,15 +72,15 @@
   }
 }
 
+
+//
 // Sizing
-// --------------------------------------------------
+//
 
-// Large
 .pagination-lg {
   @include pagination-size($padding-lg-vertical, $padding-lg-horizontal, $font-size-lg, $border-radius-lg);
 }
 
-// Small
 .pagination-sm {
   @include pagination-size($padding-sm-vertical, $padding-sm-horizontal, $font-size-sm, $border-radius-sm);
 }
diff --git a/scss/_popover.scss b/scss/_popover.scss
index d73bbd0ab9..7757fc1792 100644
--- a/scss/_popover.scss
+++ b/scss/_popover.scss
@@ -45,6 +45,7 @@
   padding: 9px 14px;
 }
 
+
 // Arrows
 //
 // .popover-arrow is outer, .popover-arrow:after is inner
diff --git a/scss/_responsive-embed.scss b/scss/_responsive-embed.scss
index 5a0e0b8860..c1ef6cb4ba 100644
--- a/scss/_responsive-embed.scss
+++ b/scss/_responsive-embed.scss
@@ -1,5 +1,7 @@
-// Embeds responsive
 //
+// Responsive embed
+// --------------------------------------------------
+
 // Credit: Nicolas Gallagher and SUIT CSS.
 
 .embed-responsive {
diff --git a/scss/_tables.scss b/scss/_tables.scss
index fc9c83edfd..ef399c0fad 100644
--- a/scss/_tables.scss
+++ b/scss/_tables.scss
@@ -1,21 +1,6 @@
 //
-// Reset tabular elements
-//
-
-// table {
-//   background-color: $table-bg;
-// }
-
-// caption {
-//   padding-top: $table-cell-padding;
-//   padding-bottom: $table-cell-padding;
-//   color: $text-muted;
-//   text-align: left;
-// }
-
-// th {
-//   text-align: left;
-// }
+// Custom tables
+// --------------------------------------------------
 
 
 //
diff --git a/scss/_utilities-responsive.scss b/scss/_utilities-responsive.scss
index bb8c784dbd..bafd964b63 100644
--- a/scss/_utilities-responsive.scss
+++ b/scss/_utilities-responsive.scss
@@ -2,6 +2,11 @@
 // Responsive: Utility classes
 // --------------------------------------------------
 
+
+//
+// Mixins
+//
+
 @each $bp in map-keys($grid-breakpoints) {
   .hidden-#{$bp}-up {
     @include media-breakpoint-up($bp) {
diff --git a/scss/_utilities.scss b/scss/_utilities.scss
index 592c800d80..64869e9cf9 100644
--- a/scss/_utilities.scss
+++ b/scss/_utilities.scss
@@ -3,10 +3,14 @@
 // --------------------------------------------------
 
 
+//
 // Floats
+//
+
 .clearfix {
   @include clearfix();
 }
+
 .center-block {
   @include center-block();
 }
@@ -14,10 +18,16 @@
 .pull-right {
   @include pull-right();
 }
+
 .pull-left {
   @include pull-left();
 }
 
+
+//
+// Screenreaders
+//
+
 .sr-only {
   @include sr-only();
 }
@@ -27,13 +37,6 @@
 }
 
 
-// Inverse
-.inverse {
-  color: $gray-lighter;
-  background-color: $gray-dark;
-}
-
-
 //
 // Spacing
 //
@@ -157,6 +160,10 @@
 }
 
 
+//
+// Text
+//
+
 // Alignment
 .text-left           { text-align: left; }
 .text-right          { text-align: right; }
@@ -170,8 +177,8 @@
 .text-uppercase      { text-transform: uppercase; }
 .text-capitalize     { text-transform: capitalize; }
 
-// Contextual colors
 
+// Contextual colors
 .text-muted {
   color: $text-muted;
 }
@@ -186,10 +193,18 @@
 
 @include text-emphasis-variant('.text-danger', $state-danger-text);
 
+
 // Contextual backgrounds
 // For now we'll leave these alongside the text classes until v4 when we can
 // safely shift things around (per SemVer rules).
 
+// Inverse
+// Todo: redo this as a proper class
+.inverse {
+  color: $gray-lighter;
+  background-color: $gray-dark;
+}
+
 .bg-primary {
   // Given the contrast here, this is the only class to have its color inverted
   // automatically.