From bf8a50901d15c240373637a698fdfc1a4094dc20 Mon Sep 17 00:00:00 2001 From: Timo Tijhof Date: Sun, 27 Apr 2014 16:10:05 +0200 Subject: [PATCH] jquery.colorUtil: Add jsduck documentation Change-Id: Idd91e07d7718b054e5827d0df0fe5302f6a97405 --- maintenance/jsduck/categories.json | 1 + maintenance/jsduck/config.json | 1 + resources/src/jquery/jquery.colorUtil.js | 105 ++++++++++++++--------- 3 files changed, 68 insertions(+), 39 deletions(-) diff --git a/maintenance/jsduck/categories.json b/maintenance/jsduck/categories.json index b1cefa3142..2d45645113 100644 --- a/maintenance/jsduck/categories.json +++ b/maintenance/jsduck/categories.json @@ -75,6 +75,7 @@ "name": "Plugins", "classes": [ "jQuery.client", + "jQuery.colorUtil", "jQuery.plugin.*" ] } diff --git a/maintenance/jsduck/config.json b/maintenance/jsduck/config.json index d0b3b3d9da..858154445f 100644 --- a/maintenance/jsduck/config.json +++ b/maintenance/jsduck/config.json @@ -21,6 +21,7 @@ "../../resources/src/jquery/jquery.badge.js", "../../resources/src/jquery/jquery.byteLimit.js", "../../resources/src/jquery/jquery.client.js", + "../../resources/src/jquery/jquery.colorUtil.js", "../../resources/src/jquery/jquery.localize.js", "../../resources/src/jquery/jquery.spinner.js", "../../resources/lib/oojs", diff --git a/resources/src/jquery/jquery.colorUtil.js b/resources/src/jquery/jquery.colorUtil.js index 37bf1767ad..be770a95e2 100644 --- a/resources/src/jquery/jquery.colorUtil.js +++ b/resources/src/jquery/jquery.colorUtil.js @@ -1,17 +1,27 @@ -/** +/*! * jQuery Color Utilities - * Written by Krinkle in 2011 + * * Released under the MIT and GPL licenses. + * * Mostly based on other plugins and functions (linted and optimized a little). * Sources cited inline. */ ( function ( $ ) { + /** + * @class jQuery.colorUtil + * @singleton + */ $.colorUtil = { - // Color Conversion function from highlightFade - // By Blair Mitchelmore - // http://jquery.offput.ca/highlightFade/ - // Parse strings looking for color tuples [255,255,255] + /** + * Parse CSS color strings looking for color tuples + * + * Based on highlightFade by Blair Mitchelmore + * + * + * @param {Array|string} color + * @return {Array} + */ getRGB: function ( color ) { /*jshint boss:true */ var result; @@ -50,9 +60,14 @@ return $.colorUtil.colors[$.trim(color).toLowerCase()]; }, - // Some named colors to work with - // From Interface by Stefan Petre - // http://interface.eyecon.ro/ + /** + * Named color map + * + * Based on Interface by Stefan Petre + * + * + * @property {Object} + */ colors: { aqua: [0,255,255], azure: [240,255,255], @@ -101,23 +116,29 @@ }, /** - * http://mjijackson.com/2008/02/rgb-to-hsl-and-rgb-to-hsv-color-model-conversion-algorithms-in-javascript - * Converts an RGB color value to HSL. Conversion formula - * adapted from http://en.wikipedia.org/wiki/HSL_color_space. - * Assumes r, g, and b are contained in the set [0, 255] and - * returns h, s, and l in the set [0, 1]. + * Convert an RGB color value to HSL. * - * @param Number R The red color value - * @param Number G The green color value - * @param Number B The blue color value - * @return Array The HSL representation + * Conversion formula based on + * + * + * Adapted from . + * + * Assumes `r`, `g`, and `b` are contained in the set `[0, 255]` and + * returns `h`, `s`, and `l` in the set `[0, 1]`. + * + * @param {number} r The red color value + * @param {number} g The green color value + * @param {number} b The blue color value + * @return {number[]} The HSL representation */ - rgbToHsl: function ( R, G, B ) { + rgbToHsl: function ( r, g, b ) { + r = r / 255; + g = g / 255; + b = b / 255; + var d, - r = R / 255, - g = G / 255, - b = B / 255, - max = Math.max( r, g, b ), min = Math.min( r, g, b ), + max = Math.max( r, g, b ), + min = Math.min( r, g, b ), h, s, l = (max + min) / 2; @@ -146,16 +167,20 @@ }, /** - * http://mjijackson.com/2008/02/rgb-to-hsl-and-rgb-to-hsv-color-model-conversion-algorithms-in-javascript - * Converts an HSL color value to RGB. Conversion formula - * adapted from http://en.wikipedia.org/wiki/HSL_color_space. - * Assumes h, s, and l are contained in the set [0, 1] and - * returns r, g, and b in the set [0, 255]. + * Convert an HSL color value to RGB. + * + * Conversion formula based on + * + * + * Adapted from . + * + * Assumes `h`, `s`, and `l` are contained in the set `[0, 1]` and + * returns `r`, `g`, and `b` in the set `[0, 255]`. * - * @param Number h The hue - * @param Number s The saturation - * @param Number l The lightness - * @return Array The RGB representation + * @param {number} h The hue + * @param {number} s The saturation + * @param {number} l The lightness + * @return {number[]} The RGB representation */ hslToRgb: function ( h, s, l ) { var r, g, b, hue2rgb, q, p; @@ -193,16 +218,18 @@ }, /** - * Get's a brighter or darker rgb() value string. + * Get a brighter or darker rgb() value string. * - * @author Krinkle + * Usage: * - * @example getCSSColorMod( 'red', +0.1 ) - * @example getCSSColorMod( 'rgb(200,50,50)', -0.2 ) + * $.colorUtil.getColorBrightness( 'red', +0.1 ); + * // > "rgb(255,50,50)" + * $.colorUtil.getColorBrightness( 'rgb(200,50,50)', -0.2 ); + * // > "rgb(118,29,29)" * - * @param Mixed currentColor current value in css - * @param Number mod wanted brightness modification between -1 and 1 - * @return String 'rgb(r,g,b)' + * @param {Mixed} currentColor Current value in css + * @param {number} mod Wanted brightness modification between -1 and 1 + * @return {string} Like `'rgb(r,g,b)'` */ getColorBrightness: function ( currentColor, mod ) { var rgbArr = $.colorUtil.getRGB( currentColor ), -- 2.20.1