Skip to content

Commit

Permalink
Mostly adding (or fixing) jsdoc param description.
Browse files Browse the repository at this point in the history
But also added "if (var)" wraps to some internal calls and added some
default values to prevent jsblocks from throwing debug errors internally.
  • Loading branch information
Joscha Rohmann committed Aug 17, 2016
1 parent fd1bc32 commit b11a50d
Show file tree
Hide file tree
Showing 7 changed files with 46 additions and 31 deletions.
8 changes: 6 additions & 2 deletions lib/blocks/core.js
Original file line number Diff line number Diff line change
Expand Up @@ -440,11 +440,15 @@
* Unwraps a jQuery instance and returns the first element
*
* @param {*} element - If jQuery element is specified it will be unwraped
* @param {Function} [callback] - Callback the element will be passed to.
* @param {*} [thisArg] - The context the callback will be executed with
* @returns {*} - The unwraped value
*
* @example {javascript}
* var articles = $('.article');
* blocks.$unwrap()
* blocks.$unwrap(articles, function (article) {
* console.log(artice.textContent);
* });
*/
$unwrap: function(element, callback, thisArg) {
callback = parseCallback(callback, thisArg);
Expand Down Expand Up @@ -682,7 +686,7 @@
* Determines if the specified value is an object
*
* @memberof blocks
* @param {[type]} obj - The value to check for if it is an object
* @param {*} obj - The value to check for if it is an object
* @returns {boolean} - Returns whether the value is an object
*/
isObject: function(obj) {
Expand Down
2 changes: 1 addition & 1 deletion src/modules/Router.js
Original file line number Diff line number Diff line change
Expand Up @@ -347,7 +347,7 @@
var optionalParameters = [];

blocks.each(routeData, function (split) {
if (blocks.has(route._optional, split.param)) {
if (route._optional && split.param && blocks.has(route._optional, split.param)) {
optionalParameters.push(split.param);
}
});
Expand Down
13 changes: 7 additions & 6 deletions src/mvc/Application.js
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ define([
* Creates an application property for a Model
*
* @memberof Application
* @param {Object)} property - An object describing the options for the current property
* @param {Object} [property] - An object describing the options for the current property
*
* @example {javascript}
*
Expand Down Expand Up @@ -144,6 +144,7 @@ define([
* Creates a new Collection
*
* @memberof Application
* @param {Object} [ModelType] - The model type the collection will be created for.
* @param {Object} prototype - The Collection object properties that will be created.
* @returns {Collection} - The Collection type with the specified properties
* @example {javascript}
Expand Down Expand Up @@ -219,10 +220,10 @@ define([
};

if (!ModelType) {
ModelType = this.Model();
ModelType = this.Model({});
} else if (!Model.prototype.isPrototypeOf(ModelType.prototype)) {
prototype = ModelType;
ModelType = this.Model();
ModelType = this.Model({});
}
prototype = prototype || {};
prototype.options = prototype.options || {};
Expand Down Expand Up @@ -286,11 +287,11 @@ define([
if (!this._started) {
this._started = true;
this._serverData = window.__blocksServerData__;

if (this._serverData && this._serverData.baseUrl) {
this._router._setBaseUrl(this._serverData.baseUrl);
}

this._createViews();
blocks.domReady(blocks.bind(this._ready, this, element));
}
Expand Down Expand Up @@ -347,7 +348,7 @@ define([
_urlChange: function (data) {
var _this = this;
var currentView = this._currentView;
var routes = this._router.routeFrom(data.url);
var routes = this._router.routeFrom(data.url) || [];
var found = false;

blocks.each(routes, function (route) {
Expand Down
9 changes: 5 additions & 4 deletions src/mvc/Collection.js
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ define([

observable._baseUpdate = observable.update;
blocks.each(blocks.observable.fn.collection, function (value, key) {
if (blocks.isFunction(value) && key.indexOf('_') !== 0) {
if (blocks.isFunction(value) && key.indexOf('_') !== 0 && blocks.isFunction(observable[key])) {
observable[key] = blocks.bind(observable[key], observable);
}
});
Expand Down Expand Up @@ -177,12 +177,13 @@ define([
return this;
},

//@todo docs -> What does it do with args ?
/**
*
* Performs updates on elements, expressions, etc. like obervable.update() when called without arguments.
*
* @memberof Collection
* @param {number} id -
* @param {Object} newValues -
* @param {number} [id] - The id of the element to trigger the update for
* @param {Object} [newValues] - The new values to apply
* @returns {Collection} - Chainable. Returns the Collection itself - return this;
*/
update: function (id, newValues) {
Expand Down
6 changes: 4 additions & 2 deletions src/mvc/Model.js
Original file line number Diff line number Diff line change
Expand Up @@ -197,10 +197,12 @@ define([
},

/**
* Applies new properties to the Model by providing an Object
* Applies new properties to the Model by providing an Object.
* If no object is provided all App.Properties will be set to their "defaulValue" or undefined.
* All observables will be set to undefined.
*
* @memberof Model
* @param {Object} dataItem - The object from which the new values will be applied
* @param {Object} [dataItem] - The object from which the new values will be applied
* @returns {Model} - Chainable. Returns itself
*/
reset: function (dataItem) {
Expand Down
8 changes: 5 additions & 3 deletions src/mvc/Property.js
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,11 @@
.on('changing', options.changing, thisArg)
.on('change', options.change, thisArg);

blocks.each(options.extenders, function (extendee) {
observable = observable.extend.apply(observable, extendee);
});
if (options.extenders) {
blocks.each(options.extenders, function (extendee) {
observable = observable.extend.apply(observable, extendee);
});
}

return observable;
};
Expand Down
31 changes: 18 additions & 13 deletions src/query/observable.js
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ define([

/**
* @namespace blocks.observable
* @param {*} initialValue -
* @param {*} [context] -
* @param {*} initialValue - The inital value of the observable. This value will also specify the functions the observable inherits (e.g. array specific functions). Do not change types of observables later.
* @param {*} [context] - The context the observable will be bound to.
* @returns {blocks.observable}
*/
blocks.observable = function (initialValue, thisArg) {
Expand Down Expand Up @@ -246,14 +246,18 @@ define([
}
}

blocks.each(this._dependencies, function updateDependency(dependency) {
updateDependencies(dependency);
dependency.update();
});
if (this._dependencies) {
blocks.each(this._dependencies, function updateDependency(dependency) {
updateDependencies(dependency);
dependency.update();
});
}

blocks.each(this._indexes, function updateIndex(observable, index) {
observable(index);
});
if (this._indexes) {
blocks.each(this._indexes, function updateIndex(observable, index) {
observable(index);
});
}

Observer.stopObserving();

Expand Down Expand Up @@ -344,7 +348,7 @@ define([
* The value could be Array, observable array or jsvalue.Array
*
* @memberof array
* @param {Array} value - The new value that will be populated
* @param {Array|Null|Undefined} [value] - The new value that will be populated
* @returns {blocks.observable} - Returns the observable itself - return this;
*
* @example {javascript}
Expand Down Expand Up @@ -567,6 +571,7 @@ define([
* @param {Function} [callback] - Optional callback function which filters which items
* to be removed. Returning a truthy value will remove the item and vice versa
* @param {*} [thisArg] - Optional this context for the callback function
* @param {boolean} [removeOne] - If set only the first entry will be removed. Mostly used in internal functions.
* @returns {blocks.observable} - Returns the observable itself - return this;
*/
removeAll: function (callback, thisArg, removeOne) {
Expand Down Expand Up @@ -827,10 +832,10 @@ define([
* Adds and/or removes elements from the observable array
*
* @memberof array
* @param {number} index An integer that specifies at what position to add/remove items.
* @param {number} index - An integer that specifies at what position to add/remove items.
* Use negative values to specify the position from the end of the array.
* @param {number} howMany The number of items to be removed. If set to 0, no items will be removed.
* @param {...*} The new item(s) to be added to the array.
* @param {number} howMany - The number of items to be removed. If set to 0, no items will be removed.
* @param {...*} [items] - The new item(s) to be added to the array.
* @returns {Array} A new array containing the removed items, if any.
*/
splice: function (index, howMany) {
Expand Down

0 comments on commit b11a50d

Please sign in to comment.