From 904c26f350a44e4906cf0a25cd363930047cf897 Mon Sep 17 00:00:00 2001 From: Benjamin Jones Date: Tue, 23 Oct 2012 11:40:23 -0700 Subject: updated jsDocs --- contexts/data/fiveui/injected/jquery-plugins.js | 88 ++++++++++++++++--------- contexts/data/fiveui/injected/prelude.js | 64 +++++++++++++++++- doc/Makefile | 4 +- 3 files changed, 119 insertions(+), 37 deletions(-) diff --git a/contexts/data/fiveui/injected/jquery-plugins.js b/contexts/data/fiveui/injected/jquery-plugins.js index 1fb084c..06c4b4a 100644 --- a/contexts/data/fiveui/injected/jquery-plugins.js +++ b/contexts/data/fiveui/injected/jquery-plugins.js @@ -24,8 +24,6 @@ if (typeof goog != 'undefined') { } /** - * FiveUI jQuery plugins - * * This module provides several useful jQuery plugins related to checking and reporting * UI consistency issues. * @@ -34,12 +32,24 @@ if (typeof goog != 'undefined') { fiveui.jqueryPlugins = fiveui.jqueryPlugins || {}; /** - * Provide a short alias for fiveui.query along the lines of the jQuery $ alias + * Provide a short alias for fiveui.query along the lines of the jQuery $ alias. + * + * 

+ * EXAMPLES:
+ *
+ *   $5("p").hasText("foo") -> jQuery object containing paragraph elements
+ *   containing the text "foo"
+ *

+ * + * @const + * */ var $5 = fiveui.query; /** * Simple proof of concept plugin + * + * @return {!object} A modified jQuery object */ fiveui.jqueryPlugins.myPlugin = function () { return this.css("border-style", "solid").css("border-color", "red"); @@ -47,35 +57,46 @@ fiveui.jqueryPlugins.myPlugin = function () { /** * Wrapper for the :contains('text') selector + * + * @param {!string} text Text to select for + * @return {!object} A modified jQuery object */ fiveui.jqueryPlugins.hasText = function (text) { return this.filter(":contains('" + text + "')") } /** - * Color checker plugin + * Color checker plugin: filters for elements whose CSS color property is + * not in the given set. * * Note: This is a special case of fiveui.jqueryPlugins.cssIsNot, i.e. * $(..).notColorSet(set) == $(..).cssIsNot("color", set, fiveui.color.colorToHex) + * @see {fiveui.color.colorToHex} + * + * @param {Array.} cset A set of allowable color strings + * @return {!object} A modified jQuery object */ fiveui.jqueryPlugins.notColorSet = function (cset) { var allowable = {}; - for (i = 0; i < cset.length; i += 1) { allowable[cset[i]] = true; } // array -> object + for (var i = 0; i < cset.length; i += 1) { allowable[cset[i]] = true; } // array -> object return this.filter(function (index) { var color = fiveui.color.colorToHex($(this).css("color")); // .css("color") returns rgb(...) return !(color in allowable); }); } -/* +/** * General CSS propetry checker plugin * - * @param{string} prop CSS property selector - * @param{string, array} set allowable values (either a string or an array of strings) - * @param{function} fn (optional) Function to apply to return values of $(this).css(prop) - * fn defaults to the identity function. + * This plugin filters for elements whose CSS property `prop` is not a member + * of the given array `cset`. The values checked are transformed using the + * optional given function `fn`. This may be used to normalize values that the + * browser returns so they can be compared to values in `cset`. * - * @return{jQuery} jQuery object + * @param {string} prop CSS property selector + * @param {string, Array.} set allowable values (either a string or an array of strings) + * @param {function(string):string=} fn Function to apply to return values of $(this).css(prop), fn defaults to the identity function. + * @return{Object} jQuery object */ fiveui.jqueryPlugins.cssIsNot = function (prop, set, fn) { var allowable = {}; @@ -92,7 +113,7 @@ fiveui.jqueryPlugins.cssIsNot = function (prop, set, fn) { }); } -/* +/** * Send a report to FiveUI reporting a problem with each element in the * jQuery object. * @@ -104,31 +125,33 @@ fiveui.jqueryPlugins.report = function (msg) { }); } -/* +/** * Visually highlight elements in the jQuery object (mostly for debugging purposes). * - * @param{string} borderHint Highlighted border color, defaults to "red" + * @param {?string=} hint Highlighted border color, defaults to "red" + * @return {!Object} A modified jQuery object */ -fiveui.jqueryPlugins.highlight = function (borderHint) { - borderHint = borderHint || "red"; // Default is "red" +fiveui.jqueryPlugins.highlight = function (hint) { + hint = hint || "red"; // Default is "red" return this.css("background-color", "rgba(255, 0, 0, 0.3)") .css("border-style", "solid") - .css("border-color", borderHint); + .css("border-color", hint); } -/* +/** * Returns a list of css properties that element in the jQuery * object have. This is useful for analysis of a given page when * writing guielines. * - * @param{string} prop CSS property to be inspected - * - * @return{object} A frequence map { "property": frequency } + * @param {!string} prop CSS property to be inspected + * @param {bool=} log Boolean which enables console logging of the result; default is `false`. + * @return {Object.} A frequence map { "property": frequency } */ -fiveui.jqueryPlugins.propDist = function (prop) { - res = {}; +fiveui.jqueryPlugins.propDist = function (prop, log) { + var res = {}; + log = log || false; this.each(function (i, elt) { - p = $(elt).css(prop) + var p = $(elt).css(prop); if (p in res) { res[p] += 1; } @@ -136,15 +159,18 @@ fiveui.jqueryPlugins.propDist = function (prop) { res[p] = 1; } }); - console.log("Distribution of property: " + prop); - for (p in res) { - console.log(" " + p + ": " + res[p]); + if (log) { + console.log("Property distribution:"); + for (var p in res) { + console.log(" " + p + ": " + res[p]); + } } - return null; + return res; } - -// register the plugins +/** + * Register the plugins. This adds methods to the jQuery.fn namespace. + */ fiveui.jqueryPlugins.init = function () { for (fn in fiveui.jqueryPlugins) { f = fiveui.jqueryPlugins[fn]; @@ -154,5 +180,3 @@ fiveui.jqueryPlugins.init = function () { } } fiveui.jqueryPlugins.init(); - -/* :vim makecmd="make -C ../../../" */ diff --git a/contexts/data/fiveui/injected/prelude.js b/contexts/data/fiveui/injected/prelude.js index f799883..6d86126 100644 --- a/contexts/data/fiveui/injected/prelude.js +++ b/contexts/data/fiveui/injected/prelude.js @@ -179,6 +179,7 @@ fiveui.word.capitalized = function(word) { /** * Check to see if a sting consists entirely of capital letters. + * * @param {!string} word The string to check for capitalization. * @returns {!boolean} */ @@ -196,11 +197,15 @@ fiveui.word.allCaps = function(word) { */ fiveui.color = {}; -/* Color check compiler. +/** + * Color check compiler. It is recommended to use the jQuery plugin + * fiveui.jqueryPlugins.cssIsNot instead. + * * @param {!string} selector The HTML element selector to check. * @param {!array} colorSet An array of strings containing the HEX values of * colors in the desired color set. * @returns {!function} A function which checks the rule + * @see fiveui.jqueryPlugins.cssIsNot */ fiveui.color.colorCheck = function (selector, colorSet) { var allowable, i, fnStr, forEachFuncStr; @@ -218,7 +223,14 @@ fiveui.color.colorCheck = function (selector, colorSet) { // function expression ?!? }; -/* covert rgb(a) colors to hex */ +/** + * Covert rgb colors to hex and abreviated hex colors to their full 3 byte + * form. + * + * @param {!string} color The color string to convert. This should be either of the form rgb(...) or #... + * @returns {!string} The color string in #XXXXXX form + * @throws {ParseError} if the rgb color string cannot be parsed + */ fiveui.color.colorToHex = function(color) { var have, need; if (color.substr(0, 1) === '#') { @@ -259,12 +271,58 @@ fiveui.color.colorToHex = function(color) { /** - * Utilities for dealing with font. + * Utilities for dealing with fonts. * * @namespace */ fiveui.font = {}; +/** + * Extracts the font-family, font-size (in px, as an int), and font-weight + * from a jQuery object. + * + * @param {!object} jElt A jQuery object to extract font info from + * @returns {!object} An object with properties: 'family', 'size', and 'weight' + * @throws {ParseError} if the font size cannot be parsed + */ +fiveui.font.getFont = function (jElt) { + var res = {}; + var sizeTxt = /(\d+)/.exec(jElt.css('font-size')); + if (!sizeTxt) { + throw { name: 'ParseError', message: 'Could not parse font size: ' + jElt.css('font-size') }; + } + else { + res.size = sizeTxt[1]; + } + res.family = jElt.css('font-family'); + res.weight = jElt.css('font-weight'); + return res; +} + +/** + * Validate a font property object extracted using fiveui.font.getFont + * + * 

+ * EXAMPLES::
+ *
+ *   > allow = { 'Verdana': { 'bold': {"10":{}, "12":{}}, 'normal': {"10":{}, "12":{}} } };
+ *   > font = { family: 'Verdana Arial sans-serif', size: "10", weight: "normal" };
+ *   > fiveui.font.validate(allow, font) -> true
+ *

+ * + * @param {!object} allow Object containing allowable font sets (see EXAMPLES) + * @param {!object} font object to check + * @returns {!boolean} + */ +fiveui.font.validate = function (allow, font) { + var x; + for (x in allow) { // loop over allowed font family keywords + if (font.family.indexOf(x) != -1) { break; } + else { return false; } + } + return (font.weight in allow[x] && font.size in allow[x][font.weight]); +} + /** * Functions outside the fiveui namespace that can be called during rule * evaluation. diff --git a/doc/Makefile b/doc/Makefile index 6d0fc25..5dc2db8 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -5,8 +5,8 @@ MAN_DEPS=$(MANUAL_SRC)/*.md $(MANUAL_SRC)/figures/*.png jsdoc-toolkit=../build/jsdoc -jsdoc: ../contexts/data/fiveui/injected/prelude.js - @$(jsdoc-toolkit) ../contexts/data/fiveui/injected/prelude.js +jsdoc: ../contexts/data/fiveui/injected/prelude.js ../contexts/data/fiveui/injected/jquery-plugins.js + @$(jsdoc-toolkit) ../contexts/data/fiveui/injected/prelude.js ../contexts/data/fiveui/injected/jquery-plugins.js .PHONY: man man: web-manual -- cgit v1.2.3