Add JSDocs

lost.styl

@@ -6,10 +6,31 @@ $old = false
 $rtl = false
 
 
+/**
+ * Sets a translucent background color to all elements it affects. Helpful while setting up, or debugging, the structure of your site to make sure all items are cleared correctly.
+ *
+ * @param {string} [$bg=blue] - A color to be lightened, so make sure you pick a darkish color.
+ *
+ * @example
+ *   section
+ *     edit(red)
+ */
+
 edit($bg = blue)
   *
     background: rgba($bg, 10%)
 
+
+/**
+ * Clearfix used to clear floated children columns. http://nicolasgallagher.com/micro-clearfix-hack
+ *
+ * @example
+ *   .parent
+ *     cf()
+ *     .child
+ *       column(1/2)
+ */
+
 cf()
   *zoom: 1
   &:before, &:after
@@ -18,6 +39,22 @@ cf()
   &:after
     clear: both
 
+
+/**
+ * Vertically and/or horizontally align nested elements.
+ *
+ * @param {string} [$direction=both] - Either vertical, v, horizontal, or h. Defaults to both.
+ *
+ * @example
+ *   .parent
+ *     align(vertical)
+ *     width: 600px
+ *     height: 400px
+ *     .child
+ *       width: 300px
+ *       height: 150px
+ */
+
 align($direction = both)
   if $old
     position: relative
@@ -51,6 +88,18 @@ align($direction = both)
       justify-content: center
       align-items: center
 
+
+/**
+ * Create a container that is centered in the middle of the page with some padding on the left and right sides of it.
+ *
+ * @param {number} [$pad=0] - Padding on the left and right side of the element. 0 by default, but feel free to increase it so containers don't touch the edge of the viewport.
+ * @param {number} [$mw=$breakpoint] - The max-width of the element.
+ *
+ * @example
+ *   section
+ *     center(45px)
+ */
+
 center($pad = 0, $mw = $breakpoint)
   max-width: $mw
   margin-right: auto
@@ -63,6 +112,20 @@ center($pad = 0, $mw = $breakpoint)
     padding-left: $pad
     padding-right: $pad
 
+
+/**
+ * Apply a negative margin on each side of the element. This is required when adding columns and such to negate their outer margins. This mixin automatically applies clearfix as it's assumed floated elements will be nested within it.
+ *
+ * @param {number} [$ratios=1] - If $old is false, a single fraction used to determine the negative left and right margins of the element. If $old is true, a collection of container ratios (fractions).
+ * @param {number} [$gut=$gutter] - The gutter width. This is typically left alone, but if you want a specific row/column combination to have a larger or smaller gutter, you need to specify the same $gut on both types of elements.
+ *
+ * @example
+ *   .parent
+ *     row()
+ *     .children
+ *       column(1/2)
+ */
+
 row($ratios = 1, $gut = $gutter)
   cf()
   if $old
@@ -74,6 +137,30 @@ row($ratios = 1, $gut = $gutter)
     margin-left: -($gut / 2)
     margin-right: -($gut / 2)
 
+
+/**
+ * Creates a column that is a fraction of the size of it's containing element with a margin on each side of the element. If $old is set to false, you don't need to pass any additional ratios (fractions), as the grid system will make use of calc(). If $old is set to true, the grid system will support more browsers, but you will need to pass additional ratios for each nested container. It's highly recommended you use the calc() syntax to avoid confusion.
+ *
+ * @param {number} [$ratios=1] - If $old is false, this is a simple fraction of the containing element's width. If $old is true, this is a collection of fractions with the containing element's fraction passed each time it is nested.
+ * @param {number} [$gut=$gutter] - The margin on each side of the element used to create a gutter. Typically this is left alone, but if you need to have a specifically large or small gutter, you will need to alter this along with the containing row's gutter so they are the same.
+ *
+ * @example
+ *   .parent
+ *     row()
+ *     .children
+ *       column(1/4)
+ *
+ * @example
+ *   .parent
+ *     row()
+ *     .child
+ *       column(1/2)
+ *       .nested-parent
+ *         row(1/2)
+ *         .nested-child
+ *           column(1/4 1/2)
+ */
+
 column($ratios = 1, $gut = $gutter)
   if $rtl
     float: right
@@ -96,6 +183,20 @@ column($ratios = 1, $gut = $gutter)
     if $gut is 0
       width: s('calc(100% * %s)', $ratios)
 
+
+/**
+ * Margin to the left or right of an elements depending on if the fraction passed is positive or negative.
+ *
+ * @param {number} [$ratios=false] - Fraction of the container to be offset.
+ * @param {number} [$gut=$gutter] - How large the gutter involved is, typically this won't be adjusted, but if you have set the columns for that row to have different gutters than default, you will need to match that gutter here as well.
+ *
+ * @example
+ *   .two-elements
+ *     column(1/3)
+ *     &:nth-child(2)
+ *       offset(1/3)
+ */
+
 offset($ratios = false, $gut = $gutter)
   if $old
     $gut = $gut * .1
@@ -122,6 +223,23 @@ offset($ratios = false, $gut = $gutter)
       if $ratios < 0
         margin-right: s('calc(-100% * %s)', $ratios)
 
+
+/**
+ * Source ordering. Useful for having an element appear above or below another element on mobile devices, and then to the opposite side on larger devices. For instance, a sidebar and article. You might want the sidebar to appear before the article on mobile, but be to the right of the article on desktop. This is how that is achieved.
+ *
+ * @param {number} [$ratios=false] - Fraction of the container to be moved by it's left value.
+ *
+ * @example
+ *   .sidebar
+ *     @media (min-width: 800px)
+ *       column(1/3)
+ *       move(2/3)
+ *   .article
+ *     @media (min-width: 800px)
+ *       column(2/3)
+ *       move(-1/3)
+ */
+
 move($ratios = false)
   position: relative
   if $old
@@ -130,19 +248,58 @@ move($ratios = false)
     $ratios = $ratios[0]
     left: s('calc(100% * %s)', $ratios)
 
+
+/**
+ * Since columns are floated, when they are of unequal height, they will misalign easily. By setting cycle() you can make sure elements are being cleared on appropriate rows.
+ *
+ * @param {number} [$item=-1] - The nth-child + 1 element to clear on. If you want a row to be 3 elements wide, then you'd pass 3.
+ *
+ * @example
+ *   .gallery
+ *     img
+ *       column(1/3)
+ *       cycle(3)
+ */
+
 cycle($item = -1)
   &:nth-child(n)
     clear: none
   &:nth-child({$item}n + 1)
     clear: both
 
-// Private
+
+/**
+ * Reverses a list of numbers (or in our case, fractions)
+ *
+ * @param {number} $list - A list of numbers or fractions to be reversed.
+ *
+ * @example
+ *   $foo: 1 2 3
+ *   _reverse($foo)
+ *
+ * @access private
+ */
+
 _reverse($list)
   result = ()
   for item in $list
     prepend(result, item)
   return result
 
+
+/**
+ * Gets a column's width and gutter size as an integer.
+ *
+ * @param {number} [$ratios=1] - A list of fractions to be used in calculating the appropriate width and gutter size returned.
+ * @param {number} [$gut=$gutter] - The gutter size used to generate an appropriate width and gutter size to be returned by the function.
+ *
+ * @example
+ *   .third
+ *     width: (_get-column(1/3, '30px')[0])%
+ *
+ * @access private
+ */
+
 _get-column($ratios = 1, $gut = $gutter)
   $ratios = _reverse($ratios)
   width = 100
@@ -151,8 +308,22 @@ _get-column($ratios = 1, $gut = $gutter)
     width = 100 * $ratio - $gut
   return width ($gut / 2)
 
+
+/**
+ * A helper class used for centering by default values.
+ *
+ * @see {center}
+ */
+
 .center
   center()
 
+
+/**
+ * A helper class used to create rows with default values.
+ *
+ * @see {row}
+ */
+
 .row
   row()