Functions and Mixin documentation first part

Author: cedric07

src/scss/02-tools/_f-assign-inputs.scss

@@ -2,7 +2,28 @@
 @use "sass:string";
 
 /**
- * Assign inputs
+ * Assign inputs - Make a variable selector with multiple inputs
+ *
+ * @author Nicolas Langle
+ *
+ * @param $inputs
+ * @param $pseudo
+ *
+ * Examples :
+ *      $text-inputs-list: 'input[type="color"]', 'input[type="date"]',
+ *         'input[type="datetime"]', 'input[type="datetime-local"]',
+ *         'input[type="email"]', 'input[type="month"]', 'input[type="number"]',
+ *         'input[type="password"]', 'input[type="search"]', 'input[type="tel"]',
+ *         'input[type="text"]', 'input[type="time"]', 'input[type="url"]',
+ *         'input[type="week"]', "input:not([type])", "textarea";
+ *
+ *      $all-text-inputs: assign-inputs($text-inputs-list);
+ *
+ *      And use as a selector :
+ *      #{(dollar)all-text-inputs} {
+ *          ...
+ *      }
+ *
  */
 
 @function assign-inputs($inputs, $pseudo: null) {

src/scss/02-tools/_f-column.scss

@@ -2,12 +2,48 @@
 @use "sass:math";
 
 /**
- * Column
+ * 1/ Column - Make a column that return a percent value
  *
- * examples :
+ * @author Nicolas Langle
+ *
+ * @param $device (based on $column-preset variable)
+ * @param $nb-column
+ * @param $nb-gutter
+ * @param $total-column
+ * @param $total-gutter
+ *
+ * Examples :
  *      column(6) 			-> return 6 column + 5 gutter of desktop preset
- * 		column('m', 6) 		-> return 6 column + 5 gutter of mobile preset
- * 		column(6, 5, 8)		-> return 6 column + 5 gutter of 8 grid size of desktop
+ *      column('m', 6) 		-> return 6 column + 5 gutter of mobile preset
+ *      column(6, 5, 8)		-> return 6 column + 5 gutter of 8 grid size of desktop
+ *
+ * ------------------------------------------------------------------------------------
+ *
+ * 2/ Column px - Make a column that return a pixel value
+ *
+ * @author Nicolas Langle
+ *
+ * @param $device (based on $column-preset variable)
+ * @param $nb-column
+ * @param $nb-gutter
+ * @param $unitless
+ *
+ * Examples :
+ *      column(6) 			-> return 6 column + 5 gutter of desktop preset with px unit
+ *      column(6, true) 	-> return 6 column + 5 gutter of desktop preset without px unit
+ *
+ * ------------------------------------------------------------------------------------
+ *
+ * 2/ Column full - Make a column that return a percent value of the full width container (100%) minus mobile external gutter width * 2
+ *
+ * @author Nicolas Langle
+ *
+ * @param $device (based on $column-preset variable)
+ * @param $nb-column
+ * @param $nb-gutter
+ *
+ * Examples :
+ *      column(6) -> return 6 column + 5 gutter of desktop preset
  *
  */
 

src/scss/02-tools/_f-context-align.scss

@@ -1,21 +1,25 @@
 /**
- * Align
+ * Align - Make a context align (editor / style)
  *
- * examples :
+ * @author Nicolas Langle
  *
+ * @param $value
+ * @param $suffix
+ *
+ * Examples :
  *      #{ context-align("wide") } .block#{ context-align() } {
  *          ... your css
  *      }
  *
-  *      return for style.scss :
- *          .block.alignwide {
- *              ... your css
- *          }
+ *      return for style.scss :
+ *      .block.alignwide {
+ *          ... your css
+ *      }
  *
  *      return for editor.scss :
- *          [data-align="wide"] > .block {
- *              ... your css
- *          }
+ *      [data-align="wide"] > .block {
+ *          ... your css
+ *      }
  *
  */
 

src/scss/02-tools/_f-context-selector.scss

@@ -1,48 +1,52 @@
 /**
- * Context selector
+ * Context selector - Make a context selector (editor / style)
  *
- * examples :
+ * @author Milan Ricoul
  *
+ * @param $default
+ * @param $editor
+ * @param $selector
+ *
+ * Examples :
  *      #{ context-selector('#main__content', '#editor', '.block') } {
  *          ... your css
  *      }
  *
  *      return for style.scss :
- *          #main__content .block {
- *              ... your css
- *          }
+ *      #main__content .block {
+ *          ... your css
+ *      }
  *
  *      return for editor.scss :
- *          #editor .block {
- *              ... your css
- *          }
+ *      #editor .block {
+ *          ... your css
+ *      }
  *
  *      $selectors: ".blocks-gallery-image,", ".blocks-gallery-item";
  *      #{ context-selector('.wp-block-gallery', '.blocks-gallery-grid', selectors) } {
  *          ... your css
  *      }
  *
  *      return for style.scss :
- *          .wp-block-gallery .blocks-gallery-image,
- *          .wp-block-gallery .blocks-gallery-item {
- *              ... your css
- *          }
+ *      .wp-block-gallery .blocks-gallery-image,
+ *      .wp-block-gallery .blocks-gallery-item {
+ *          ... your css
+ *      }
  *
  *      return for editor.scss :
- *          .blocks-gallery-grid .blocks-gallery-image,
- *          .blocks-gallery-grid .blocks-gallery-item {
- *              ... your css
- *          }
+ *      .blocks-gallery-grid .blocks-gallery-image,
+ *      .blocks-gallery-grid .blocks-gallery-item {
+ *          ... your css
+ *      }
  *
  *      It can be used to define a variable :
- *
  *      $parent: context-selector('#main__content', '#editor')
- *
  *      #{(dollar)parent} > .block {
  *          ... your css
  *      }
  *
  *      the variable $entry-file-name is defined in style.scss and editor.scss
+ *
  */
 
 @function context-selector($default: null, $editor: null, $selector: null) {

src/scss/02-tools/_f-easings.scss

@@ -1,12 +1,17 @@
 @use "sass:math";
 
 /**
- * Easings
+ * Easings - for CSS animations
  *
- *      converted from source: https://github.com/ai/easings.net/blob/master/src/easings/easingsFunctions.ts
- *      each ease receive a value $x in a range of 0 to 1
+ * @author Nicolas Langle
  *
- *      examples :
+ * @param $value
+ * @param $suffix
+ *
+ * converted from source: https://github.com/ai/easings.net/blob/master/src/easings/easingsFunctions.ts
+ * each ease receive a value $x in a range of 0 to 1
+ *
+ * Examples :
  *
  *      @for (dollar)i from 0 through 10 {
  *          .test {
@@ -55,6 +60,7 @@
  *      ease-in-out-bounce
  *
  */
+
 $easings-const-c1: 1.70158;
 $easings-const-c2: $easings-const-c1 * 1.525;
 $easings-const-c3: $easings-const-c1 + 1;

src/scss/02-tools/_f-em.scss

@@ -1,9 +1,23 @@
 @use "sass:math";
 
 /**
- * Em
+ * Em - Convert value from px to em
+ *
+ * Source : https://github.com/thoughtbot/carnival/blob/master/sass/bourbon/functions/_px-to-em.scss
+ *
+ * @author Nicolas Langle
+ *
+ * @param $pxval
+ * @param $base
+ *
+ * Examples :
+ *
+ *      $font-size: 16px; // don't use em function whitout param
+ *
+ *      .test {
+ *          font-size: em(112px, $font-size);
+ *      }
  *
- * convert value from px to em
  */
 
 @function em($pxval, $base: $font-size-base) {

src/scss/02-tools/_f-get-gutter-width.scss

@@ -1,9 +1,26 @@
 @use "sass:map";
 
 /**
- * Get Gutter width
+ * Get Gutter width - Get the value of gutter according to the preset
+ *
+ * @author Milan Ricoul
+ *
+ * @param $preset (based on $column-preset variable)
+ *
+ * Examples :
+ *
+ *      .test {
+ *          display: grid;
+ *          grid-template-column: repeat(3, 1fr);
+ *          gap: get-gutter-width(); // return gutter width desktop preset
+ *      }
+ *
+ *      .test {
+ *          display: grid;
+ *          grid-template-column: repeat(3, 1fr);
+ *          gap: get-gutter-width('m'); // return gutter width mobile preset
+ *      }
  *
- * get the value of gutter according to the preset
  */
 
 @function get-gutter($preset: d) {

src/scss/02-tools/_f-get-svg-url.scss

@@ -1,11 +1,32 @@
 @use "sass:map";
 
 /**
- * get-svg-url
+ * Get svg url - Display a svg in background image
  *
- * examples :
- *      get-svg-url("arrow")
- *      get-svg-url("arrow", $color-primary)
+ * @author Nicolas Langle
+ *
+ * @param $name
+ * @param $fill
+ * @param $opacity
+ * @param $style
+ *
+ * Examples :
+ *
+ *      .my-icon {
+ *          background-image: get-svg-url("arrow", $color-primary);
+ *          background-repeat: no-repeat;
+ *          background-position: center;
+ *          background-size: 20px;
+ *      }
+ *
+ *      // With css mask (for icon with current color)
+ *      .my-icon {
+ *          width; 20px;
+ *          height: 20px;
+ *          background-color: currentColor;
+ *          -webkit-mask-image: get-svg-url("arrow", "");
+ *          mask-image: get-svg-url("arrow", "");
+ *      }
  *
  */
 

src/scss/02-tools/_f-strip-units.scss

@@ -1,7 +1,18 @@
 @use "sass:math";
 
 /**
- * Strip units
+ * Strip units - Remove unit
+ *
+ * @author Nicolas Langle
+ *
+ * @param $value
+ *
+ * Examples :
+ *
+ *      strip-units(10px)  -> return 10
+ *      strip-units(10%)   -> return 10
+ *      strip-units(10)    -> return 10
+ *
  */
 
 @function strip-units($value) {