jenkins-bot has submitted this change and it was merged.
Change subject: doc: Improve overall documentation and fix minor issues
......................................................................
doc: Improve overall documentation and fix minor issues
Fixes:
* Turn url into a clickable link in Markdown using <http://>
(unlike wikitext, Markdown doesn't autolink urls).
* Override method name as indexed for oo.getHash.keySortReplacer.
(defaulted to being indexed as oo#keySortReplacer since it uses
last property level + class name, which works great with
Foo.prototype or jQuery.fn, but less so in this case).
* Link plain text identifiers that weren't being recognised
(oo.getHash -> OO.getHash etc.)
* Remove useless descriptions so they show up when querying
items that need descriptions.
* Remove erroneous @example.
* Fix ignored "bindings" @property in EventEmitter.
It wasn't being picked up because @property is not supported
inside an @constructor comment.
Consistently:
* Omit redundant @method.
* Use @return instead of @returns.
* Start captions with a capital.
* Treat primary item (event, method, class, property) descriptions
as sentences ending in full setop.
* Treat secondary item (param, return, etc.) descriptions
as captions not ending in a full stop unless they form one
or more paragraphs.
* Primary item descriptions should start with a single line
in the imperative mood: "Get this", "do that", "make something";
as opposed to: "Gets this", "Does that", "Makes something".
* Indent continued line with one extra space.
Change-Id: I25346437c95b1440341f4c1399afb93a6dd3ded1
---
M jsduck.categories.json
M src/EventEmitter.js
M src/Factory.js
M src/Registry.js
M src/core.js
5 files changed, 44 insertions(+), 53 deletions(-)
Approvals:
Esanders: Looks good to me, approved
jenkins-bot: Verified
diff --git a/jsduck.categories.json b/jsduck.categories.json
index b322656..3bae581 100644
--- a/jsduck.categories.json
+++ b/jsduck.categories.json
@@ -17,7 +17,14 @@
{
"name": "JavaScript",
"classes": [
- "Array", "Boolean", "Date", "Function",
"Number", "Object", "RegExp", "String"
+ "Array",
+ "Boolean",
+ "Date",
+ "Function",
+ "Number",
+ "Object",
+ "RegExp",
+ "String"
]
}
]
diff --git a/src/EventEmitter.js b/src/EventEmitter.js
index 87bdc47..776d12e 100644
--- a/src/EventEmitter.js
+++ b/src/EventEmitter.js
@@ -1,13 +1,16 @@
/**
- * Event emitter.
- *
* @class OO.EventEmitter
*
* @constructor
- * @property {Object} bindings
*/
oo.EventEmitter = function OoEventEmitter() {
// Properties
+
+ /**
+ * Storage of bound event handlers by event name.
+ *
+ * @property
+ */
this.bindings = {};
};
@@ -18,7 +21,6 @@
*
* If the callback/context are already bound to the event, they will not be
bound again.
*
- * @method
* @param {string} event Type of event to listen to
* @param {Function} callback Function to call when event occurs
* @param {Array} [args] Arguments to pass to listener, will be prepended to
emitted arguments
@@ -63,7 +65,6 @@
/**
* Adds a one-time listener to a specific event.
*
- * @method
* @param {string} event Type of event to listen to
* @param {Function} listener Listener to call when event occurs
* @chainable
@@ -79,7 +80,6 @@
/**
* Remove a specific listener from a specific event.
*
- * @method
* @param {string} event Type of event to remove listener from
* @param {Function} [callback] Listener to remove, omit to remove all
* @param {Object} [context=null] Object used context for callback function or
method
@@ -124,13 +124,13 @@
/**
* Emit an event.
+ *
* TODO: Should this be chainable? What is the usefulness of the boolean
* return value here?
*
- * @method
* @param {string} event Type of event
* @param {Mixed} args First in a list of variadic arguments passed to event
handler (optional)
- * @returns {boolean} If event was handled by at least one listener
+ * @return {boolean} If event was handled by at least one listener
*/
oo.EventEmitter.prototype.emit = function ( event ) {
var i, len, binding, bindings, args;
@@ -154,12 +154,11 @@
/**
* Connect event handlers to an object.
*
- * @method
* @param {Object} context Object to call methods on when events occur
* @param
{Object.<string,string>|Object.<string,Function>|Object.<string,Array>} methods
List of
- * event bindings keyed by event name containing either method names,
functions or arrays containing
- * method name or function followed by a list of arguments to be passed to
callback before emitted
- * arguments
+ * event bindings keyed by event name containing either method names,
functions or arrays containing
+ * method name or function followed by a list of arguments to be passed to
callback before emitted
+ * arguments
* @chainable
*/
oo.EventEmitter.prototype.connect = function ( context, methods ) {
@@ -194,7 +193,6 @@
/**
* Disconnect event handlers from an object.
*
- * @method
* @param {Object} context Object to disconnect methods from
* @param
{Object.<string,string>|Object.<string,Function>|Object.<string,Array>}
[methods] List of
* event bindings keyed by event name containing either method names or
functions
diff --git a/src/Factory.js b/src/Factory.js
index fd05590..262c625 100644
--- a/src/Factory.js
+++ b/src/Factory.js
@@ -1,6 +1,4 @@
/**
- * Object factory.
- *
* @class OO.Factory
* @extends OO.Registry
*
@@ -25,14 +23,12 @@
*
* Classes must have a static `name` property to be registered.
*
- * @example
* function MyClass() {};
* // Adds a static property to the class defining a symbolic name
* MyClass.static = { 'name': 'mine' };
* // Registers class with factory, available via symbolic name 'mine'
* factory.register( MyClass );
*
- * @method
* @param {Function} constructor Constructor to use when creating object
* @throws {Error} Name must be a string and must not be empty
* @throws {Error} Constructor must be a function
@@ -57,10 +53,9 @@
* Name is used to look up the constructor to use, while all additional
arguments are passed to the
* constructor directly, so leaving one out will pass an undefined to the
constructor.
*
- * @method
* @param {string} name Object name
* @param {Mixed...} [args] Arguments to pass to the constructor
- * @returns {Object} The new object
+ * @return {Object} The new object
* @throws {Error} Unknown object name
*/
oo.Factory.prototype.create = function ( name ) {
diff --git a/src/Registry.js b/src/Registry.js
index ee2d80d..5413c30 100644
--- a/src/Registry.js
+++ b/src/Registry.js
@@ -1,6 +1,4 @@
/**
- * Data registry.
- *
* @class OO.Registry
* @mixins OO.EventEmitter
*
@@ -33,7 +31,6 @@
*
* Only the base name will be registered, overriding any existing entry with
the same base name.
*
- * @method
* @param {string|string[]} name Symbolic name or list of symbolic names
* @param {Mixed} data Data to associate with symbolic name
* @fires register
@@ -57,13 +54,12 @@
};
/**
- * Gets data for a given symbolic name.
+ * Get data for a given symbolic name.
*
* Lookups are done using the base name.
*
- * @method
* @param {string} name Symbolic name
- * @returns {Mixed|undefined} Data associated with symbolic name
+ * @return {Mixed|undefined} Data associated with symbolic name
*/
oo.Registry.prototype.lookup = function ( name ) {
return this.registry[name];
diff --git a/src/core.js b/src/core.js
index 8e74931..bc0a1b0 100644
--- a/src/core.js
+++ b/src/core.js
@@ -13,7 +13,6 @@
/**
* Assert whether a value is a plain object or not.
*
- * @method
* @param {Mixed} obj
* @return {boolean}
*/
@@ -48,7 +47,7 @@
* This is how prototypal inheritance works, it can only be one straight chain
* (just like classical inheritance in PHP for example). If you need to work
with
* multiple constructors consider storing an instance of the other
constructor in a
- * property instead, or perhaps use a mixin (see oo.mixinClass).
+ * property instead, or perhaps use a mixin (see OO.mixinClass).
*
* function Thing() {}
* Thing.prototype.exists = function () {};
@@ -72,7 +71,6 @@
* x.walk();
* x instanceof Thing && x instanceof Person && x instanceof Jumper;
*
- * @method
* @param {Function} targetFn
* @param {Function} originFn
* @throws {Error} If target already inherits from origin
@@ -126,7 +124,6 @@
* OO.inheritClass( FooBar, Foo );
* OO.mixinClass( FooBar, ContextLazyLoad );
*
- * @method
* @param {Function} targetFn
* @param {Function} originFn
*/
@@ -174,7 +171,6 @@
* foo2.getAge(); // 21
* foo.getAge(); // 22
*
- * @method
* @param {Object} origin
* @return {Object} Clone of origin
*/
@@ -193,11 +189,10 @@
};
/**
- * Gets an array of all property values in an object.
+ * Get an array of all property values in an object.
*
- * @method
* @param {Object} Object to get values from
- * @returns {Array} List of object values
+ * @return {Array} List of object values
*/
oo.getObjectValues = function ( obj ) {
var key, values;
@@ -223,11 +218,10 @@
* the other. An asymmetrical test may also be performed, which checks only
that properties in the
* first object are present in the second object, but not the inverse.
*
- * @method
* @param {Object} a First object to compare
* @param {Object} b Second object to compare
* @param {boolean} [asymmetrical] Whether to check only that b contains
values from a
- * @returns {boolean} If the objects contain the same values as each other
+ * @return {boolean} If the objects contain the same values as each other
*/
oo.compare = function ( a, b, asymmetrical ) {
var aValue, bValue, aType, bType, k;
@@ -256,10 +250,9 @@
*
* Copies are deep, and will either be an object or an array depending on
`source`.
*
- * @method
* @param {Object} source Object to copy
* @param {Function} [callback] Applied to leaf values before they added to
the clone
- * @returns {Object} Copy of source object
+ * @return {Object} Copy of source object
*/
oo.copy = function ( source, callback ) {
var key, sourceValue, sourceType, destination;
@@ -297,8 +290,9 @@
};
/**
- * Generates a hash of an object based on its name and data.
- * Performance optimization:
http://jsperf.com/ve-gethash-201208#/toJson_fnReplacerIfAoForElse
+ * Generate a hash of an object based on its name and data.
+ *
+ * Performance optimization:
<http://jsperf.com/ve-gethash-201208#/toJson_fnReplacerIfAoForElse>
*
* To avoid two objects with the same values generating different hashes, we
utilize the replacer
* argument of JSON.stringify and sort the object by key as it's being
serialized. This may or may
@@ -309,20 +303,21 @@
* ourselves. This allows classes to define custom hashing.
*
* @param {Object} val Object to generate hash for
- * @returns {string} Hash of object
+ * @return {string} Hash of object
*/
oo.getHash = function ( val ) {
return JSON.stringify( val, oo.getHash.keySortReplacer );
};
/**
- * Helper function for oo.getHash which sorts objects by key.
+ * Helper function for OO.getHash which sorts objects by key.
*
* This is a callback passed into JSON.stringify.
*
+ * @method getHash_keySortReplacer
* @param {string} key Property name of value being replaced
* @param {Mixed} val Property value to replace
- * @returns {Mixed} Replacement value
+ * @return {Mixed} Replacement value
*/
oo.getHash.keySortReplacer = function ( key, val ) {
var normalized, keys, i, len;
@@ -352,13 +347,13 @@
/**
* Compute the union (duplicate-free merge) of a set of arrays.
*
- * Arrays values must be convertable to object keys (strings)
+ * Arrays values must be convertable to object keys (strings).
*
* By building an object (with the values for keys) in parallel with
- * the array, a new item's existence in the union can be computed faster
+ * the array, a new item's existence in the union can be computed faster.
*
* @param {Array...} arrays Arrays to union
- * @returns {Array} Union of the arrays
+ * @return {Array} Union of the arrays
*/
oo.simpleArrayUnion = function () {
var i, ilen, arr, j, jlen,
@@ -383,16 +378,16 @@
*
* An intersection checks the item exists in 'b' while difference checks it
doesn't.
*
- * Arrays values must be convertable to object keys (strings)
+ * Arrays values must be convertable to object keys (strings).
*
* By building an object (with the values for keys) of 'b' we can
- * compute the result faster
+ * compute the result faster.
*
* @private
* @param {Array} a First array
* @param {Array} b Second array
* @param {boolean} includeB Whether to items in 'b'
- * @returns {Array} Combination (intersection or difference) of arrays
+ * @return {Array} Combination (intersection or difference) of arrays
*/
function simpleArrayCombine( a, b, includeB ) {
var i, ilen, isInB,
@@ -416,11 +411,11 @@
/**
* Compute the intersection of two arrays (items in both arrays).
*
- * Arrays values must be convertable to object keys (strings)
+ * Arrays values must be convertable to object keys (strings).
*
* @param {Array} a First array
* @param {Array} b Second array
- * @returns {Array} Intersection of arrays
+ * @return {Array} Intersection of arrays
*/
oo.simpleArrayIntersection = function ( a, b ) {
return simpleArrayCombine( a, b, true );
@@ -429,11 +424,11 @@
/**
* Compute the difference of two arrays (items in 'a' but not 'b').
*
- * Arrays values must be convertable to object keys (strings)
+ * Arrays values must be convertable to object keys (strings).
*
* @param {Array} a First array
* @param {Array} b Second array
- * @returns {Array} Intersection of arrays
+ * @return {Array} Intersection of arrays
*/
oo.simpleArrayDifference = function ( a, b ) {
return simpleArrayCombine( a, b, false );
--
To view, visit https://gerrit.wikimedia.org/r/117201
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I25346437c95b1440341f4c1399afb93a6dd3ded1
Gerrit-PatchSet: 5
Gerrit-Project: oojs/core
Gerrit-Branch: master
Gerrit-Owner: Krinkle <krinklem...@gmail.com>
Gerrit-Reviewer: Esanders <esand...@wikimedia.org>
Gerrit-Reviewer: Jforrester <jforres...@wikimedia.org>
Gerrit-Reviewer: Krinkle <krinklem...@gmail.com>
Gerrit-Reviewer: jenkins-bot <>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
