From 14556d2a8f38ad5cb6bc55471f8af25bb7fa394f Mon Sep 17 00:00:00 2001
From: Hugo Giraudel <hugo.giraudel@gmail.com>
Date: Mon, 23 Nov 2015 00:19:17 +0100
Subject: [PATCH] Minor SassDoc improvements

---
 scss/forms/_error.scss     |  1 +
 scss/grid/_column.scss     |  3 ++-
 scss/grid/_flex-grid.scss  |  3 +++
 scss/grid/_layout.scss     |  3 ++-
 scss/grid/_position.scss   |  1 +
 scss/grid/_row.scss        |  5 ++++-
 scss/util/_breakpoint.scss | 10 ++++++++--
 scss/util/_color.scss      | 14 +++++++-------
 scss/util/_mixins.scss     |  6 +++++-
 scss/util/_selector.scss   |  1 +
 scss/util/_unit.scss       |  9 ++++++++-
 scss/util/_value.scss      | 13 +++++++++++--
 12 files changed, 53 insertions(+), 16 deletions(-)

diff --git a/scss/forms/_error.scss b/scss/forms/_error.scss
index 5e456a6ee..9e52b6e59 100644
--- a/scss/forms/_error.scss
+++ b/scss/forms/_error.scss
@@ -35,6 +35,7 @@ $input-error-font-size: rem-calc(12) !default;
 $input-error-font-weight: $global-weight-bold !default;
 
 /// Styles the background and border of an input field to have an error state.
+///
 /// @param {Color} $background [$alert-color] - Color to use for the background and border.
 @mixin form-input-error(
   $background: $alert-color
diff --git a/scss/grid/_column.scss b/scss/grid/_column.scss
index 821fe8168..7b50df572 100644
--- a/scss/grid/_column.scss
+++ b/scss/grid/_column.scss
@@ -14,7 +14,7 @@
 ///   - A single digit will make the column span that number of columns wide, taking into account the column count of the parent row.
 ///   - A string of the format "x of y" will make a column that is *x* columns wide, assuming *y* total columns for the parent.
 ///
-/// @return {Number} A calculated percentage value.
+/// @returns {Number} A calculated percentage value.
 @function grid-column($columns) {
   $width: 0%;
 
@@ -73,6 +73,7 @@
 }
 
 /// Creates a grid column row. This is the equivalent of adding `.row` and `.column` to the same element.
+///
 /// @param {Number} $gutter [$grid-column-gutter] - Width of the gutters on either side of the column row.
 @mixin grid-column-row(
   $gutter: $grid-column-gutter
diff --git a/scss/grid/_flex-grid.scss b/scss/grid/_flex-grid.scss
index 86f076a21..c5f8367e3 100644
--- a/scss/grid/_flex-grid.scss
+++ b/scss/grid/_flex-grid.scss
@@ -7,6 +7,7 @@
 ////
 
 /// Creates a container for a flex grid row.
+///
 /// @param {Keyword|List} $behavior [null]
 ///   Modifications to the default grid styles. `nest` indicates the row will be placed inside another row. `collapse` indicates that the columns inside this row will not have padding. `nest collapse` combines both behaviors.
 /// @param {Number} $width [$grid-row-width] - Maximum width of the row.
@@ -46,6 +47,7 @@
 /// Calculates the `flex` property for a flex grid column. It accepts all of the same values as the basic `grid-column()` function, along with two extras:
 ///   - `null` (the default) will make the column expand to fill space.
 ///   - `shrink` will make the column contract, so it only takes up the horizontal space it needs.
+///
 /// @param {Mixed} $columns [null] - Width of the column.
 @function flex-grid-column($columns: null) {
   $flex: 1 1 0px;
@@ -61,6 +63,7 @@
 }
 
 /// Creates a column for a flex grid. By default, the column will stretch to the full width of its container, but this can be overridden with sizing classes, or by using the `unstack` class on the parent flex row.
+///
 /// @param {Mixed} $columns [null] - Width of the column. Refer to the `flex-grid-column()` function to see possible values.
 /// @param {Number} $gutter [$grid-column-gutter] - Space between columns, added as a left and right padding.
 @mixin flex-grid-column(
diff --git a/scss/grid/_layout.scss b/scss/grid/_layout.scss
index d2dd856d5..4b3761d36 100644
--- a/scss/grid/_layout.scss
+++ b/scss/grid/_layout.scss
@@ -7,8 +7,9 @@
 ////
 
 /// Sizes child elements so that `$n` number of items appear on each row.
+///
 /// @param {Number} $n - Number of elements to display per row.
-/// @param {String} $selector ['.column, .columns'] - Selector(s) to use for child elements.
+/// @param {String} $selector ['.column'] - Selector(s) to use for child elements.
 @mixin grid-layout(
   $n,
   $selector: '.column'
diff --git a/scss/grid/_position.scss b/scss/grid/_position.scss
index f7ed8b55f..9cafac9ad 100644
--- a/scss/grid/_position.scss
+++ b/scss/grid/_position.scss
@@ -7,6 +7,7 @@
 ////
 
 /// Reposition a column.
+///
 /// @param {Number} $position - Direction and amount to move. The column will move equal to the width of the column count specified. A positive number will push the column to the right, while a negative number will pull it to the left.
 @mixin grid-column-position($position) {
   @if type-of($position) == 'number' {
diff --git a/scss/grid/_row.scss b/scss/grid/_row.scss
index 973d26e63..23fbbbdac 100644
--- a/scss/grid/_row.scss
+++ b/scss/grid/_row.scss
@@ -8,10 +8,11 @@
 
 /// Change the behavior of columns defined inside this mixin to use a different column count.
 /// @content
+///
 /// @param {Number} $columns - Number of columns to use.
 /// @param {Booleam} $root [false]
 ///   If `false`, selectors inside this mixin will nest inside the parent selector.
-///   If `tru`, selectors will not nest.
+///   If `true`, selectors will not nest.
 @mixin grid-context(
   $columns,
   $root: false
@@ -33,10 +34,12 @@
 
 /// Creates a grid row.
 /// @content
+///
 /// @param {Number} $columns [null] - Column count for this row. `null` will use the default column count.
 /// @param {Keywords} $behavior [null]
 ///   Modifications to the default grid styles. `nest` indicates the row will be placed inside another row. `collapse` indicates that the columns inside this row will not have padding. `nest collapse` combines both behaviors.
 /// @param {Number} $width [$grid-row-width] - Maximum width of the row.
+/// @param {Boolean} $cf [true] - Whether or not to include a clearfix.
 @mixin grid-row(
   $columns: null,
   $behavior: null,
diff --git a/scss/util/_breakpoint.scss b/scss/util/_breakpoint.scss
index 50384a2fc..20291c939 100644
--- a/scss/util/_breakpoint.scss
+++ b/scss/util/_breakpoint.scss
@@ -23,7 +23,8 @@ $breakpoints: (
 $breakpoint-classes: (small medium large) !default;
 
 /// Generates a media query string matching the input value. Refer to the documentation for the `breakpoint()` mixin to see what the possible inputs are.
-/// @param {Keyword|Number} $val - Breakpoint name, or px, rem, or em value to process.
+///
+/// @param {Keyword|Number} $val [small] - Breakpoint name, or px, rem, or em value to process.
 @function breakpoint($val: small) {
   // Size or keyword
   $bp: nth($val, 1);
@@ -117,8 +118,9 @@ $breakpoint-classes: (small medium large) !default;
 ///  - If a pixel value is passed, it will be converted to an em value using `$rem-base`.
 ///  - If a rem value is passed, the unit will be changed to em.
 ///  - If an em value is passed, the value will be used as-is.
-/// @content
+///
 /// @param {Keyword|Number} $value - Breakpoint name, or px, rem, or em value to process.
+///
 /// @output If the breakpoint is "0px and larger", outputs the content as-is. Otherwise, outputs the content wrapped in a media query.
 @mixin breakpoint($value) {
   $str: breakpoint($value);
@@ -138,7 +140,9 @@ $breakpoint-classes: (small medium large) !default;
 
 /// Convers the breakpoints map to a URL-encoded string, like this: `key1=value1&key2=value2`. The value is then dropped into the CSS for a special `<meta>` tag, which is read by the Foundation JavaScript. This is how we transfer values from Sass to JavaScript, so they can be defined in one place.
 /// @access private
+///
 /// @param {Map} $map - Map to convert.
+///
 /// @returns {String} A string containing the map's contents.
 @function -zf-bp-serialize($map) {
   $str: '';
@@ -152,8 +156,10 @@ $breakpoint-classes: (small medium large) !default;
 
 /// Find the next key in a map.
 /// @access private
+///
 /// @param {Map} $map - Map to traverse.
 /// @param {Mixed} $key - Key to use as a starting point.
+///
 /// @returns {Mixed} The value for the key after `$key`, if `$key` was found. If `$key` was not found, or `$key` was the last value in the map, returns `null`.
 @function -zf-map-next($map, $key) {
   // Store the values of the map as a list, so we can access them with nth
diff --git a/scss/util/_color.scss b/scss/util/_color.scss
index e01845fef..74c456b1c 100644
--- a/scss/util/_color.scss
+++ b/scss/util/_color.scss
@@ -8,10 +8,10 @@
 
 /// Checks the lightness of `$color`, and if it passes the `$threshold` of lightness, it returns the `$yes` color. Otherwise, it returns the `$no` color. Use this function to dynamically output a foreground color based on a given background color.
 ///
-/// @param {color} $color - Color to check the lightness of.
-/// @param {color} $yes [$black] - Color to return if `$color` is light.
-/// @param {color} $no [$white] - Color to return if `$color` is dark.
-/// @param {percentage} $threshold [60%] - Threshold of lightness to check against.
+/// @param {Color} $color - Color to check the lightness of.
+/// @param {Color} $yes [$black] - Color to return if `$color` is light.
+/// @param {Color} $no [$white] - Color to return if `$color` is dark.
+/// @param {Percentage} $threshold [60%] - Threshold of lightness to check against.
 ///
 /// @returns {Color} The $yes color or $no color.
 @function foreground($color, $yes: $black, $no: $white, $threshold: 60%) {
@@ -28,9 +28,9 @@
 
 /// Scales a color to be lighter if it's light, or darker if it's dark. Use this function to tint a color appropriate to its lightness.
 ///
-/// @param {color} $color - Color to scale.
-/// @param {percentage} $scale [5%] - Amount to scale up or down.
-/// @param {percentage} $threshold [40%] - Threshold of lightness to check against.
+/// @param {Color} $color - Color to scale.
+/// @param {Percentage} $scale [5%] - Amount to scale up or down.
+/// @param {Percentage} $threshold [40%] - Threshold of lightness to check against.
 ///
 /// @returns {Color} A scaled color.
 @function smart-scale($color, $scale: 5%, $threshold: 40%) {
diff --git a/scss/util/_mixins.scss b/scss/util/_mixins.scss
index 882e19a2f..c30f11f72 100644
--- a/scss/util/_mixins.scss
+++ b/scss/util/_mixins.scss
@@ -7,6 +7,7 @@
 ////
 
 /// Creates a CSS triangle, which can be used for dropdown arrows, dropdown pips, and more. Use this mixin inside a `&::before` or `&::after` selector, to attach the triangle to an existing element.
+///
 /// @param {Number} $triangle-size - Width of the triangle.
 /// @param {Color} $triangle-color - Color of the triangle.
 /// @param {Keyword} $triangle-direction - Direction the triangle points. Can be `top`, `right`, `bottom`, or `left`.
@@ -40,6 +41,7 @@
 }
 
 /// Creates a menu icon with a set width, height, number of bars, and colors. The mixin uses the height of the icon and the weight of the bars to determine spacing. <div class="docs-example-burger"></div>
+///
 /// @param {Color} $color - Color to use for the icon.
 /// @param {Color} $color-hover - Color to use when the icon is hovered over.
 /// @param {Number} $width - Width of the icon.
@@ -105,6 +107,7 @@
 
 /// Adds a downward-facing triangle as a background image to an element. The image is formatted as an SVG, making it easy to change the color. Because Internet Explorer doesn't support encoded SVGs as background images, a PNG fallback is also included.
 /// There are two PNG fallbacks: a black triangle and a white triangle. The one used depends on the lightness of the input color.
+///
 /// @param {Color} $color [$black] - Color to use for the triangle.
 @mixin background-triangle($color: $black) {
   $rgb: 'rgb(#{red($color)}, #{green($color)}, #{blue($color)})';
@@ -136,9 +139,10 @@
 }
 
 /// Adds CSS for a "quantity query" selector that automatically sizes elements based on how many there are inside a container.
+/// @link http://alistapart.com/article/quantity-queries-for-css Quantity Queries for CSS
+///
 /// @param {Number} $max - Maximum number of items to detect. The higher this number is, the more CSS that's required to cover each number of items.
 /// @param {Keyword} $elem [li] - Tag to use for sibling selectors.
-/// @link http://alistapart.com/article/quantity-queries-for-css Quantity Queries for CSS
 @mixin auto-width($max, $elem: li) {
   @for $i from 2 through $max {
     &:nth-last-child(#{$i}):first-child,
diff --git a/scss/util/_selector.scss b/scss/util/_selector.scss
index cf85359ad..38c9112ce 100644
--- a/scss/util/_selector.scss
+++ b/scss/util/_selector.scss
@@ -7,6 +7,7 @@
 ////
 
 /// Generates a selector with every text input type. You can also filter the list to only output a subset of those selectors.
+///
 /// @param {List|Keyword} $types [()] - A list of text input types to use. Leave blank to use all of them.
 @function text-inputs($types: ()) {
   $return: ();
diff --git a/scss/util/_unit.scss b/scss/util/_unit.scss
index 1c889396e..ff770def5 100644
--- a/scss/util/_unit.scss
+++ b/scss/util/_unit.scss
@@ -14,15 +14,19 @@
 $rem-base: 16px !default;
 
 /// Removes the unit (e.g. px, em, rem) from a value, returning the number only.
+///
 /// @param {Number} $num - Number to strip unit from.
+///
 /// @returns {Number} The same number, sans unit.
 @function strip-unit($num) {
   @return $num / ($num * 0 + 1);
 }
 
 /// Converts one or more pixel values into matching rem values.
+///
 /// @param {Number|List} $values - One or more values to convert. Be sure to separate them with spaces and not commas. If you need to convert a comma-separated list, wrap the list in parentheses.
 /// @param {Number} $base [$rem-base] - The base value to use when calculating the `rem`. If you're using Foundation out of the box, this is 16px.
+///
 /// @returns {List} A list of converted values.
 @function rem-calc($values, $base: $rem-base) {
   $rem-values: ();
@@ -55,9 +59,12 @@ $rem-base: 16px !default;
 }
 
 /// Converts a pixel value to matching rem value. *Any* value passed, regardless of unit, is assumed to be a pixel value. By default, the base pixel value used to calculate the rem value is taken from the `$rem-base` variable.
+/// @access private
+///
 /// @param {Number} $value - Pixel value to convert.
+/// @param {Number} $base [$rem-base] - Base for pixel conversion.
+///
 /// @returns {Number} A number in rems, calculated based on the given value and the base pixel value. rem values are passed through as is.
-/// @access private
 @function -zf-to-rem($value, $base: $rem-base) {
   // Calculate rem if units for $value is not rem
   @if (unit($value) != 'rem') {
diff --git a/scss/util/_value.scss b/scss/util/_value.scss
index 9935b4c01..7d4b0f0d3 100644
--- a/scss/util/_value.scss
+++ b/scss/util/_value.scss
@@ -7,7 +7,9 @@
 ////
 
 /// Determine if a value is not falsey, in CSS terms. Falsey values are `null`, `none`, `0` with any unit, or an empty list.
-/// @param $val - Value to check.
+///
+/// @param {Mixed} $val - Value to check.
+///
 /// @returns {Boolean} `true` if `$val` is not falsey.
 @function hasvalue($val) {
   @if $val == null or $val == none {
@@ -23,8 +25,10 @@
 }
 
 /// Determine a top/right/bottom/right value on a padding, margin, etc. property, no matter how many values were passed in. Use this function if you need to know the specific side of a value, but don't know if the value is using a shorthand format.
+///
 /// @param {List|Number} $val - Value to analyze. Should be a shorthand sizing property, e.g. "1em 2em 1em"
 /// @param {Keyword} $side - Side to return. Should be `top`, `right`, `bottom`, or `left`.
+///
 /// @returns {Number} A single value based on `$val` and `$side`.
 @function get-side($val, $side) {
   $length: length($val);
@@ -59,8 +63,10 @@
 }
 
 /// Given border $val, find a specific element of the border, which is $elem. The possible values for $elem are width, style, and color.
+///
 /// @param {List} $val - Border value to find a value in.
 /// @param {Keyword} $elem - Border component to extract.
+///
 /// @returns {Mixed} If the value exists, returns the value. If the value is not in the border definition, the function will return a 0px width, solid style, or black border.
 @function get-border-value($val, $elem) {
   // Find the width, style, or color and return it
@@ -88,6 +94,7 @@
 
 /// Calculates x^y, where x is `$base` and y is `$power`.
 /// @access private
+///
 /// @param {Number} $base - Base number (x).
 /// @param {Number} $power - Exponent (y).
 @function pow($base, $power) {
@@ -97,9 +104,11 @@
 
 // TODO: Remove this (it's used by the grid but is overkill)
 /// Given a user-defined list of keywords and a list of possible keywords, find the ones that were passed in.
+/// @access private
+///
 /// @param {List} $opts - List of values to find keywords in.
 /// @param {List} $seeking - List of all possible keywords.
-/// @access private
+///
 /// @returns {Map} A map of all keywords in $seeking. If a keyword was found in $opts, its value is true, otherwise false.
 @function -zf-get-options($opts, $seeking) {
   @if type-of($opts) != 'list' {
-- 
2.47.2