Permalink
Browse files

platform: Add newlines to JSDoc descriptions, cleanup unit tests, and…

… update DocDown submodule. [jddalton]
  • Loading branch information...
1 parent 1bdbd9c commit c079ee529e74388a78dbd7c4c09d9d468bfa13b2 @jdalton jdalton committed Apr 8, 2012
Showing with 199 additions and 106 deletions.
  1. +12 −12 doc/README.md
  2. +30 −1 platform.js
  3. +156 −92 test/test.js
  4. +1 −1 vendor/docdown
View
24 doc/README.md
@@ -34,7 +34,7 @@
<!-- div -->
-### <a id="platform" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L782" title="View in source">`platform`</a>
+### <a id="platform" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L810" title="View in source">`platform`</a>
*(Object)*: The platform object.
[&#9650;][1]
@@ -43,7 +43,7 @@
<!-- div -->
-### <a id="platform.description" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L812" title="View in source">`platform.description`</a>
+### <a id="platform.description" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L844" title="View in source">`platform.description`</a>
*(String, Null)*: The platform description.
[&#9650;][1]
@@ -52,7 +52,7 @@
<!-- div -->
-### <a id="platform.layout" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L819" title="View in source">`platform.layout`</a>
+### <a id="platform.layout" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L852" title="View in source">`platform.layout`</a>
*(String, Null)*: The name of the browser layout engine.
[&#9650;][1]
@@ -61,7 +61,7 @@
<!-- div -->
-### <a id="platform.manufacturer" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L826" title="View in source">`platform.manufacturer`</a>
+### <a id="platform.manufacturer" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L860" title="View in source">`platform.manufacturer`</a>
*(String, Null)*: The name of the product's manufacturer.
[&#9650;][1]
@@ -70,7 +70,7 @@
<!-- div -->
-### <a id="platform.name" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L796" title="View in source">`platform.name`</a>
+### <a id="platform.name" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L826" title="View in source">`platform.name`</a>
*(String, Null)*: The name of the browser/environment.
[&#9650;][1]
@@ -79,7 +79,7 @@
<!-- div -->
-### <a id="platform.os" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L803" title="View in source">`platform.os`</a>
+### <a id="platform.os" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L834" title="View in source">`platform.os`</a>
*(String, Null)*: The name of the operating system.
[&#9650;][1]
@@ -88,7 +88,7 @@
<!-- div -->
-### <a id="platform.prerelease" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L833" title="View in source">`platform.prerelease`</a>
+### <a id="platform.prerelease" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L868" title="View in source">`platform.prerelease`</a>
*(String, Null)*: The alpha/beta release indicator.
[&#9650;][1]
@@ -97,7 +97,7 @@
<!-- div -->
-### <a id="platform.product" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L840" title="View in source">`platform.product`</a>
+### <a id="platform.product" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L876" title="View in source">`platform.product`</a>
*(String, Null)*: The name of the product hosting the browser.
[&#9650;][1]
@@ -106,7 +106,7 @@
<!-- div -->
-### <a id="platform.ua" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L847" title="View in source">`platform.ua`</a>
+### <a id="platform.ua" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L884" title="View in source">`platform.ua`</a>
*(String, Null)*: The browser's user agent string.
[&#9650;][1]
@@ -115,7 +115,7 @@
<!-- div -->
-### <a id="platform.version" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L789" title="View in source">`platform.version`</a>
+### <a id="platform.version" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L818" title="View in source">`platform.version`</a>
*(String, Null)*: The browser/environment version.
[&#9650;][1]
@@ -124,7 +124,7 @@
<!-- div -->
-### <a id="platform.parse" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L219" title="View in source">`platform.parse([ua = navigator.userAgent])`</a>
+### <a id="platform.parse" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L231" title="View in source">`platform.parse([ua = navigator.userAgent])`</a>
Creates a new platform object.
[&#9650;][1]
@@ -139,7 +139,7 @@ Creates a new platform object.
<!-- div -->
-### <a id="platform.toString" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L497" title="View in source">`platform.toString()`</a>
+### <a id="platform.toString" href="https://github.com/bestiejs/platform.js/blob/master/platform.js#L521" title="View in source">`platform.toString()`</a>
Return platform description when the platform object is coerced to a string.
[&#9650;][1]
View
31 platform.js
@@ -59,6 +59,7 @@
/**
* Capitalizes a string value.
+ *
* @private
* @param {String} string The string to capitalize.
* @returns {String} The capitalized string.
@@ -70,6 +71,7 @@
/**
* An iteration utility for arrays and objects.
+ *
* @private
* @param {Array|Object} object The object to iterate over.
* @param {Function} callback The function called per iteration.
@@ -89,6 +91,7 @@
/**
* Trim and conditionally capitalize string values.
+ *
* @private
* @param {String} string The string to format.
* @returns {String} The formatted string.
@@ -102,6 +105,7 @@
/**
* Iterates over an object's own properties, executing the `callback` for each.
+ *
* @private
* @param {Object} object The object to iterate over.
* @param {Function} callback The function executed per own property.
@@ -114,6 +118,7 @@
/**
* Gets the internal [[Class]] of a value.
+ *
* @private
* @param {Mixed} value The value.
* @returns {String} The [[Class]].
@@ -126,6 +131,7 @@
/**
* Checks if an object has the specified key as a direct property.
+ *
* @private
* @param {Object} object The object to check.
* @param {String} key The key to check for.
@@ -161,6 +167,7 @@
* Host objects can return type values that are different from their actual
* data type. The objects we are concerned with usually return non-primitive
* types of object, function, or unknown.
+ *
* @private
* @param {Mixed} object The owner of the property.
* @param {String} property The property to check.
@@ -173,7 +180,9 @@
}
/**
- * Prepares a string for use in a RegExp constructor by making hyphens and spaces optional.
+ * Prepares a string for use in a RegExp constructor by making hyphens and
+ * spaces optional.
+ *
* @private
* @param {String} string The string to qualify.
* @returns {String} The qualified string.
@@ -184,6 +193,7 @@
/**
* A bare-bones` Array#reduce` like utility function.
+ *
* @private
* @param {Array} array The array to iterate over.
* @param {Function} callback The function called per iteration.
@@ -200,6 +210,7 @@
/**
* Removes leading and trailing whitespace from a string.
+ *
* @private
* @param {String} string The string to trim.
* @returns {String} The trimmed string.
@@ -212,6 +223,7 @@
/**
* Creates a new platform object.
+ *
* @memberOf platform
* @param {String} [ua = navigator.userAgent] The user agent string.
* @returns {Object} A platform object.
@@ -358,6 +370,7 @@
/**
* Picks the layout engine from an array of guesses.
+ *
* @private
* @param {Array} guesses An array of guesses.
* @returns {String|Null} The detected layout engine.
@@ -372,6 +385,7 @@
/**
* Picks the manufacturer from an array of guesses.
+ *
* @private
* @param {Array} guesses An array of guesses.
* @returns {String|Null} The detected manufacturer.
@@ -389,6 +403,7 @@
/**
* Picks the browser name from an array of guesses.
+ *
* @private
* @param {Array} guesses An array of guesses.
* @returns {String|Null} The detected browser name.
@@ -403,6 +418,7 @@
/**
* Picks the OS name from an array of guesses.
+ *
* @private
* @param {Array} guesses An array of guesses.
* @returns {String|Null} The detected OS name.
@@ -451,6 +467,7 @@
/**
* Picks the product name from an array of guesses.
+ *
* @private
* @param {Array} guesses An array of guesses.
* @returns {String|Null} The detected product name.
@@ -479,6 +496,7 @@
/**
* Resolves the version using an array of UA patterns.
+ *
* @private
* @param {Array} patterns An array of UA patterns.
* @returns {String|Null} The detected version.
@@ -494,6 +512,7 @@
/**
* Return platform description when the platform object is coerced to a string.
+ *
* @name toString
* @memberOf platform
* @type Function
@@ -784,27 +803,31 @@
/**
* The platform object.
+ *
* @name platform
* @type Object
*/
return {
/**
* The browser/environment version.
+ *
* @memberOf platform
* @type String|Null
*/
'version': name && version && (description.unshift(version), version),
/**
* The name of the browser/environment.
+ *
* @memberOf platform
* @type String|Null
*/
'name': name && (description.unshift(name), name),
/**
* The name of the operating system.
+ *
* @memberOf platform
* @type String|Null
*/
@@ -814,41 +837,47 @@
/**
* The platform description.
+ *
* @memberOf platform
* @type String|Null
*/
'description': description.length ? description.join(' ') : ua,
/**
* The name of the browser layout engine.
+ *
* @memberOf platform
* @type String|Null
*/
'layout': layout && layout[0],
/**
* The name of the product's manufacturer.
+ *
* @memberOf platform
* @type String|Null
*/
'manufacturer': manufacturer,
/**
* The alpha/beta release indicator.
+ *
* @memberOf platform
* @type String|Null
*/
'prerelease': prerelease,
/**
* The name of the product hosting the browser.
+ *
* @memberOf platform
* @type String|Null
*/
'product': product,
/**
* The browser's user agent string.
+ *
* @memberOf platform
* @type String|Null
*/
View
248 test/test.js
@@ -23,6 +23,7 @@
/**
* An iteration utility for arrays.
+ *
* @private
* @param {Array} object The array to iterate over.
* @param {Function} callback The function called per iteration.
@@ -38,6 +39,7 @@
/**
* Iterates over an object's own properties, executing the `callback` for each.
+ *
* @private
* @param {Object} object The object to iterate over.
* @param {Function} callback The function executed per own property.
@@ -50,6 +52,7 @@
/**
* Checks if an object has the specified key as a direct property.
+ *
* @private
* @param {Object} object The object to check.
* @param {String} key The key to check for.
@@ -81,6 +84,7 @@
/**
* Modify a string by replacing named tokens with matching object property values.
+ *
* @private
* @param {String} string The string to modify.
* @param {Object} object The template object.
@@ -97,6 +101,7 @@
* Host objects can return type values that are different from their actual
* data type. The objects we are concerned with usually return non-primitive
* types of object, function, or unknown.
+ *
* @private
* @param {Mixed} object The owner of the property.
* @param {String} property The property to check.
@@ -110,6 +115,7 @@
/**
* Returns a platform object of a simulated environment.
+ *
* @private
* @param {Object} options The options object to simulate environment objects.
* @returns {Object} The modified string.
@@ -171,6 +177,7 @@
/**
* An object of UA variations.
+ *
* @type Object
*/
var Tests = {
@@ -1738,107 +1745,164 @@
QUnit.module('platform' + (window.document ? '' : ': ' + platform));
- each(['description', 'layout', 'manufacturer', 'name', 'os', 'prerelease', 'product', 'version'], function(name) {
- test('platform.' + name, function() {
- forOwn(Tests, function(value, key) {
- var platform = getPlatform(value);
- value = name == 'description' ? key : value[name];
- value = value ? interpolate(value, { 'alpha': '\u03b1', 'beta': '\u03b2' }) : null;
- equal(platform && platform[name], value, String(platform));
+ (function() {
+ each(['description', 'layout', 'manufacturer', 'name', 'os', 'prerelease', 'product', 'version'], function(name) {
+ test('has the correct `platform.' + name + '` property', function() {
+ forOwn(Tests, function(value, key) {
+ var platform = getPlatform(value);
+ value = name == 'description' ? key : value[name];
+ value = value ? interpolate(value, { 'alpha': '\u03b1', 'beta': '\u03b2' }) : null;
+ equal(platform && platform[name], value, String(platform));
+ });
});
});
- });
- test('check null values', function() {
- forOwn(Tests, function(value) {
- forOwn(getPlatform(value), function(value, key) {
- !value && strictEqual(value, null, 'platform.' + key);
+ test('has correct null values', function() {
+ forOwn(Tests, function(value) {
+ forOwn(getPlatform(value), function(value, key) {
+ !value && strictEqual(value, null, 'platform.' + key);
+ });
});
});
- });
- test('no ua', function() {
- forOwn(getPlatform({}), function(value, key) {
- if (typeof value != 'function') {
- strictEqual(value, null, 'platform.' + key);
+ test('handles no user agent', function() {
+ forOwn(getPlatform({}), function(value, key) {
+ if (typeof value != 'function') {
+ strictEqual(value, null, 'platform.' + key);
+ }
+ });
+ });
+
+ test('supports loading Platform.js as a module', function() {
+ if (window.document && window.require) {
+ equal((platform2 || {}).description, platform.description);
+ } else {
+ ok(true, 'test skipped');
}
});
- });
-
- test('platform.parse', function() {
- // avoid false negative when the UA string being tested matches the browser's
- var parse = function(ua) { return platform.parse(ua + ';'); };
-
- var actual = parse('Mozilla/5.0 (Windows; U; en-US) AppleWebKit/531.9 (KHTML, like Gecko) AdobeAIR/2.5');
- var expected = 'Adobe AIR 2.5 (like Safari 4.x)';
- equal(actual.description, expected, 'parse Adobe Air');
-
- actual = parse('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_2) AppleWebKit/535.2 (KHTML, like Gecko) Chrome/15.0.874.106 Safari/535.2');
- expected = 'Chrome 15.0.874.106 on Mac OS X 10.7.2';
- equal(actual.description, expected, 'parse Chrome');
-
- actual = parse('Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:8.0) Gecko/20100101 Firefox/8.0');
- expected = 'Firefox 8.0 on Mac OS X 10.7';
- equal(actual.description, expected, 'parse Firefox');
-
- actual = parse('Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1; Trident/4.0)');
- expected = 'IE 7.0 on Windows XP';
- equal(actual.description, expected, 'parse IE');
-
- actual = parse('Opera/9.80 (Macintosh; Intel Mac OS X 10.7.2; U; Edition Next; en) Presto/2.9.220 Version/12.00');
- expected = 'Opera 12.00 on Mac OS X 10.7.2';
- equal(actual.description, expected, 'parse Opera');
-
- actual = parse('Mozilla/5.0 (Windows NT 5.1; U; en; rv:1.8.1) Gecko/20061208 Firefox/2.0.0 Opera 10.10');
- expected = 'Opera 10.10 (identifying as Firefox 2.0.0) on Windows XP';
- equal(actual.description, expected, 'parse Opera description identifying as Firefox 2.0.0');
-
- expected = 'Presto';
- equal(actual.layout, expected, 'parse Opera layout identifying as Firefox 2.0.0');
-
- actual = parse('Mozilla/4.0 (compatible; MSIE 8.0; Mac_PowerPC; en) Opera 10.52');
- expected = 'Opera 10.52 (identifying as IE 8.0)';
- equal(actual.description, expected, 'parse Opera description identifying as IE 8.0');
-
- actual = parse('Mozilla/5.0 (compatible; MSIE 9.0; Mac_PowerPC; en) Opera 12.00');
- expected = 'Opera 12.00 (identifying as IE 9.0)';
- equal(actual.description, expected, 'parse Opera description identifying as IE 9.0');
-
- actual = parse('Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7.2; en; rv:2.0) Gecko/20100101 Firefox/4.0');
- expected = 'Opera (masking as Firefox 4.0) on Mac OS X 10.7.2';
- equal(actual.description, expected, 'parse Opera description masking as Firefox 4.0');
-
- actual = parse('Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 5.1; en)');
- expected = 'Opera (masking as IE 8.0)';
- equal(actual.description, expected, 'parse Opera description masking as IE 8.0');
-
- actual = parse('Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 5.1; Trident/5.0; en)');
- expected = 'Opera (masking as IE 9.0)';
- equal(actual.description, expected, 'parse Opera description masking as IE 9.0');
-
- actual = parse('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_2) AppleWebKit/534.51.22 (KHTML, like Gecko) Version/5.1.1 Safari/534.51.22');
- expected = 'Safari 5.1.1 on Mac OS X 10.7.2';
- equal(actual.description, expected, 'parse Safari');
-
- actual = parse('Mozilla/5.0 (X11; U; Cygwin; C -) AppleWebKit/527+ (KHTML, like Gecko, Safari/419.3) PhantomJS/1.0.0');
- expected = 'PhantomJS 1.0.0 (like Safari 4.x) on Cygwin';
- equal(actual.description, expected, 'parse PhantomJS');
- });
-
- test('platform.toString', function() {
- var description = platform.description;
- platform.description = null;
- ok(typeof platform.toString() == 'string', 'returns a string');
- platform.description = description;
- });
-
- test('require("platform")', function() {
- if (window.document && window.require) {
- equal((platform2 || {}).description, platform.description, 'require("platform")');
- } else {
- ok(true, 'test skipped');
+ }());
+
+ /*--------------------------------------------------------------------------*/
+
+ QUnit.module('platform.parse');
+
+ (function() {
+ function parse(ua) {
+ // avoid false negative when the UA string being tested matches the browser's
+ return platform.parse(ua + ';');
}
- });
+
+ test('parses Adobe Air', function() {
+ var actual = parse('Mozilla/5.0 (Windows; U; en-US) AppleWebKit/531.9 (KHTML, like Gecko) AdobeAIR/2.5'),
+ expected = 'Adobe AIR 2.5 (like Safari 4.x)';
+
+ equal(actual.description, expected);
+ });
+
+ test('parses Chrome', function() {
+ var actual = parse('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_2) AppleWebKit/535.2 (KHTML, like Gecko) Chrome/15.0.874.106 Safari/535.2'),
+ expected = 'Chrome 15.0.874.106 on Mac OS X 10.7.2';
+
+ equal(actual.description, expected);
+ });
+
+ test('parses Firefox', function() {
+ var actual = parse('Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:8.0) Gecko/20100101 Firefox/8.0'),
+ expected = 'Firefox 8.0 on Mac OS X 10.7';
+
+ equal(actual.description, expected);
+ });
+
+ test('parses IE', function() {
+ var actual = parse('Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1; Trident/4.0)'),
+ expected = 'IE 7.0 on Windows XP';
+
+ equal(actual.description, expected);
+ });
+
+ test('parses Opera', function() {
+ var actual = parse('Opera/9.80 (Macintosh; Intel Mac OS X 10.7.2; U; Edition Next; en) Presto/2.9.220 Version/12.00'),
+ expected = 'Opera 12.00 on Mac OS X 10.7.2';
+
+ equal(actual.description, expected);
+ });
+
+ test('parses Opera description identifying as Firefox 2.0.0', function() {
+ var actual = parse('Mozilla/5.0 (Windows NT 5.1; U; en; rv:1.8.1) Gecko/20061208 Firefox/2.0.0 Opera 10.10'),
+ expected = 'Opera 10.10 (identifying as Firefox 2.0.0) on Windows XP';
+
+ equal(actual.description, expected);
+ });
+
+ test('parses Opera layout identifying as Firefox 2.0.0', function() {
+ var actual = parse('Mozilla/5.0 (Windows NT 5.1; U; en; rv:1.8.1) Gecko/20061208 Firefox/2.0.0 Opera 10.10'),
+ expected = 'Presto';
+
+ equal(actual.layout, expected);
+ });
+
+ test('parses Opera description identifying as IE 8.0', function() {
+ var actual = parse('Mozilla/4.0 (compatible; MSIE 8.0; Mac_PowerPC; en) Opera 10.52'),
+ expected = 'Opera 10.52 (identifying as IE 8.0)';
+
+ equal(actual.description, expected);
+ });
+
+ test('parses Opera description identifying as IE 9.0', function() {
+ var actual = parse('Mozilla/5.0 (compatible; MSIE 9.0; Mac_PowerPC; en) Opera 12.00'),
+ expected = 'Opera 12.00 (identifying as IE 9.0)';
+
+ equal(actual.description, expected);
+ });
+
+ test('parses Opera description masking as Firefox 4.0', function() {
+ var actual = parse('Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7.2; en; rv:2.0) Gecko/20100101 Firefox/4.0'),
+ expected = 'Opera (masking as Firefox 4.0) on Mac OS X 10.7.2';
+
+ equal(actual.description, expected);
+ });
+
+ test('parses Opera description masking as IE 8.0', function() {
+ var actual = parse('Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 5.1; en)'),
+ expected = 'Opera (masking as IE 8.0)';
+
+ equal(actual.description, expected);
+ });
+
+ test('parses Opera description masking as IE 9.0', function() {
+ var actual = parse('Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 5.1; Trident/5.0; en)'),
+ expected = 'Opera (masking as IE 9.0)';
+
+ equal(actual.description, expected);
+ });
+
+ test('parses Safari', function() {
+ var actual = parse('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_2) AppleWebKit/534.51.22 (KHTML, like Gecko) Version/5.1.1 Safari/534.51.22'),
+ expected = 'Safari 5.1.1 on Mac OS X 10.7.2';
+
+ equal(actual.description, expected);
+ });
+
+ test('parses PhantomJS', function() {
+ var actual = parse('Mozilla/5.0 (X11; U; Cygwin; C -) AppleWebKit/527+ (KHTML, like Gecko, Safari/419.3) PhantomJS/1.0.0'),
+ expected = 'PhantomJS 1.0.0 (like Safari 4.x) on Cygwin';
+
+ equal(actual.description, expected);
+ });
+ }());
+
+ /*--------------------------------------------------------------------------*/
+
+ QUnit.module('platform.toString');
+
+ (function() {
+ test('returns a string when `platform.description` is `null`', function() {
+ var description = platform.description;
+ platform.description = null;
+ ok(typeof platform.toString() == 'string');
+ platform.description = description;
+ });
+ }());
/*--------------------------------------------------------------------------*/
2 vendor/docdown
@@ -1 +1 @@
-Subproject commit 0bfb31d878fd6055de7ae1233b792e6e9472a4ce
+Subproject commit 75260c7e815594528ceb48d28277c56008c13c24

0 comments on commit c079ee5

Please sign in to comment.