_add.scss in singularitygs-1.0.5

- old
+ new
@@ -1,10 +1,29 @@
-@function add-gutter($gutter-definition) {
-  $parsed: parse-add($gutter-definition);
+// Accepts a gutter definition in the human-readable format. Converts it to the internal format,
+// appends it to a list of gutter and returns the resulting list.
+//
+// Note that this function only returns a new list, it does not modify the source list.
+//
+// add-gutter($grid-definition, $append-to-list)
+// - $gutter-definition : <definition>  See documentation for syntax:
+//                                      https://github.com/Team-Sass/Singularity/wiki/Creating-Grids
+// - $append-to-list    : [list]        A list to append to.
+//                                      Defaults to $gutters if none is specified.
+@function add-gutter($gutter-definition, $append-to-list: $gutters) {
+  $parsed: parse-add($gutter-definition); // Converts the definiton to a temporary format:
+                                          // either `((<gutter>))` or `((<gutter>) (<breakpoint>))`
+  $gutter:      nth($parsed, 1); // E. g. `(<gutter>)`.
+  $breakpoint:  nth($parsed, 2); // Either `(<breakpoint>)` or false.
+  $list-length: length($append-to-list);
 
-  @if nth($parsed, 2) == false and length($gutters) == 0 {
-    @return nth($parsed, 1);
+  // Check whether the definition will be the first one in the list
+  // and whether it has no breakpoint specified.
+  @if $breakpoint == false and $list-length == 0 {
+    // Returns the first item of the list, e. g. `(<gutter>)`
+    @return $gutter;
   }
   @else {
-    @return append($gutters, (nth($parsed, 1) nth($parsed, 2)), 'comma');
+    // Appends to a comma-separated list of definitions in the internal format
+    // and returns it, e. g. `(<gutter>), (<gutter> <breakpoint>), (<gutter> <breakpoint>)`
+    @return append($append-to-list, ($gutter $breakpoint), 'comma');
   }
-}
\ No newline at end of file
+}