From 44832cbbdcfb1e5753f24edc55218f4fd3c467c1 Mon Sep 17 00:00:00 2001 From: Slava Kim Date: Sun, 2 Nov 2014 02:44:19 -0800 Subject: [PATCH] Add return types and properties types in JSDoc to a lot of methods --- packages/accounts-base/accounts_common.js | 1 + packages/blaze/preamble.js | 4 ++++ packages/blaze/template.js | 7 +++++++ packages/blaze/view.js | 1 + packages/check/match.js | 8 ++++++-- packages/ddp/common.js | 4 ++++ packages/ddp/livedata_common.js | 7 ++++--- packages/ddp/livedata_server.js | 6 +++--- packages/meteor/client_environment.js | 3 +++ packages/meteor/cordova_environment.js | 2 ++ packages/meteor/helpers.js | 1 + packages/tracker/tracker.js | 11 +++++++++++ scripts/admin/jsdoc/jsdoc-conf.json | 2 +- 13 files changed, 48 insertions(+), 9 deletions(-) diff --git a/packages/accounts-base/accounts_common.js b/packages/accounts-base/accounts_common.js index 21a8d88ebbe..0c15aeba154 100644 --- a/packages/accounts-base/accounts_common.js +++ b/packages/accounts-base/accounts_common.js @@ -136,6 +136,7 @@ if (Meteor.isClient) { /** * @summary A [Mongo.Collection](#collections) containing user documents. * @locus Anywhere + * @type {Mongo.Collection} */ Meteor.users = new Mongo.Collection("users", { _preventAutopublish: true, diff --git a/packages/blaze/preamble.js b/packages/blaze/preamble.js index 1928c72359d..b90acdb3c33 100644 --- a/packages/blaze/preamble.js +++ b/packages/blaze/preamble.js @@ -1,3 +1,7 @@ +/** + * @namespace Blaze + * @summary The namespace for all Blaze-related methods and classes. + */ Blaze = {}; // Utility to HTML-escape a string. Included for legacy reasons. diff --git a/packages/blaze/template.js b/packages/blaze/template.js index 7de3c03d55a..cb7bbe3589b 100644 --- a/packages/blaze/template.js +++ b/packages/blaze/template.js @@ -178,6 +178,7 @@ Blaze.TemplateInstance = function (view) { * @instance * @summary The [View](#blaze_view) object for this invocation of the template. * @locus Client + * @type {Blaze.View} */ this.view = view; this.data = null; @@ -188,6 +189,7 @@ Blaze.TemplateInstance = function (view) { * @instance * @summary The first top-level DOM node in this template instance. * @locus Client + * @type {DOMNode} */ this.firstNode = null; @@ -197,6 +199,7 @@ Blaze.TemplateInstance = function (view) { * @instance * @summary The last top-level DOM node in this template instance. * @locus Client + * @type {DOMNode} */ this.lastNode = null; }; @@ -205,6 +208,7 @@ Blaze.TemplateInstance = function (view) { * @summary Find all elements matching `selector` in this template instance, and return them as a JQuery object. * @locus Client * @param {String} selector The CSS selector to match, scoped to the template contents. + * @returns {DOMNode[]} */ Blaze.TemplateInstance.prototype.$ = function (selector) { var view = this.view; @@ -217,6 +221,7 @@ Blaze.TemplateInstance.prototype.$ = function (selector) { * @summary Find all elements matching `selector` in this template instance. * @locus Client * @param {String} selector The CSS selector to match, scoped to the template contents. + * @returns {DOMNode[]} */ Blaze.TemplateInstance.prototype.findAll = function (selector) { return Array.prototype.slice.call(this.$(selector)); @@ -226,6 +231,7 @@ Blaze.TemplateInstance.prototype.findAll = function (selector) { * @summary Find one element matching `selector` in this template instance. * @locus Client * @param {String} selector The CSS selector to match, scoped to the template contents. + * @returns {DOMNode} */ Blaze.TemplateInstance.prototype.find = function (selector) { var result = this.$(selector); @@ -283,6 +289,7 @@ Template.prototype.events = function (eventMap) { * @memberOf Template * @summary The [template instance](#template_inst) corresponding to the current template helper, event handler, callback, or autorun. If there isn't one, `null`. * @locus Client + * @returns Blaze.TemplateInstance */ Template.instance = function () { var view = Blaze.currentView; diff --git a/packages/blaze/view.js b/packages/blaze/view.js index 69c15b32870..1e268e046de 100644 --- a/packages/blaze/view.js +++ b/packages/blaze/view.js @@ -394,6 +394,7 @@ Blaze._isContentEqual = function (a, b) { /** * @summary The View corresponding to the current template helper, event handler, callback, or autorun. If there isn't one, `null`. * @locus Client + * @type {Blaze.View} */ Blaze.currentView = null; diff --git a/packages/check/match.js b/packages/check/match.js index e86704e08c3..4562952de52 100644 --- a/packages/check/match.js +++ b/packages/check/match.js @@ -8,7 +8,7 @@ var currentArgumentChecker = new Meteor.EnvironmentVariable; /** * @summary Check that a value matches a [pattern](#matchpatterns). * If the value does not match the pattern, throw a `Match.Error`. - * + * * Particularly useful to assert that arguments to a function have the right * types and structure. * @locus Anywhere @@ -37,6 +37,10 @@ check = function (value, pattern) { } }; +/** + * @namespace Match + * @summary The namespace for all Match types and methods. + */ Match = { Optional: function (pattern) { return new Optional(pattern); @@ -76,7 +80,7 @@ Match = { // XXX maybe also implement a Match.match which returns more information about // failures but without using exception handling or doing what check() // does with _failIfArgumentsAreNotAllChecked and Meteor.Error conversion - + /** * @summary Returns true if the value matches the pattern. * @locus Anywhere diff --git a/packages/ddp/common.js b/packages/ddp/common.js index c36556da160..5b52884312c 100644 --- a/packages/ddp/common.js +++ b/packages/ddp/common.js @@ -1,2 +1,6 @@ +/** + * @namespace DDP + * @summary The namespace for DDP-related methods. + */ DDP = {}; LivedataTest = {}; diff --git a/packages/ddp/livedata_common.js b/packages/ddp/livedata_common.js index 1367d8d913e..544429c9bda 100644 --- a/packages/ddp/livedata_common.js +++ b/packages/ddp/livedata_common.js @@ -22,13 +22,14 @@ MethodInvocation = function (options) { // purposes). not currently true except in a client such as a browser, // since there's usually no point in running stubs unless you have a // zero-latency connection to the user. - + /** * @summary Access inside a method invocation. Boolean value, true if this invocation is a stub. * @locus Anywhere * @name isSimulation * @memberOf MethodInvocation * @instance + * @type {Boolean} */ this.isSimulation = options.isSimulation; @@ -39,7 +40,7 @@ MethodInvocation = function (options) { this._calledUnblock = false; // current user id - + /** * @summary The id of the user that made this method call, or `null` if no user was logged in. * @locus Anywhere @@ -54,7 +55,7 @@ MethodInvocation = function (options) { this._setUserId = options.setUserId || function () {}; // On the server, the connection this method call came in on. - + /** * @summary Access inside a method invocation. The [connection](#meteor_onconnection) that this method was received on. `null` if the method is not associated with a connection, eg. a server initiated method call. * @locus Server diff --git a/packages/ddp/livedata_server.js b/packages/ddp/livedata_server.js index d249d56dd46..569fa6160f7 100644 --- a/packages/ddp/livedata_server.js +++ b/packages/ddp/livedata_server.js @@ -901,7 +901,7 @@ var Subscription = function ( self._ready = false; // Part of the public API: the user of this sub. - + /** * @summary Access inside the publish function. The id of the logged-in user, or `null` if no user is logged in. * @locus Server @@ -1082,7 +1082,7 @@ _.extend(Subscription.prototype, { // server (and clean up its _subscriptions table) we don't actually provide a // mechanism for an app to notice this (the subscribe onError callback only // triggers if there is an error). - + /** * @summary Call inside the publish function. Stops this client's subscription; the `onError` callback is *not* invoked on the client. * @locus Server @@ -1364,7 +1364,7 @@ _.extend(Server.prototype, { * (it lets us determine whether to print a warning suggesting * that you turn off autopublish.) */ - + /** * @summary Publish a record set. * @memberOf Meteor diff --git a/packages/meteor/client_environment.js b/packages/meteor/client_environment.js index c684a59febe..646bf231ef0 100644 --- a/packages/meteor/client_environment.js +++ b/packages/meteor/client_environment.js @@ -8,6 +8,7 @@ Meteor = { * @summary Boolean variable. True if running in client environment. * @locus Anywhere * @static + * @type {Boolean} */ isClient: true, @@ -15,6 +16,7 @@ Meteor = { * @summary Boolean variable. True if running in server environment. * @locus Anywhere * @static + * @type {Boolean} */ isServer: false }; @@ -24,6 +26,7 @@ if (typeof __meteor_runtime_config__ === 'object' && /** * @summary `Meteor.settings` contains deployment-specific configuration options. You can initialize settings by passing the `--settings` option (which takes the name of a file containing JSON data) to `meteor run` or `meteor deploy`. When running your server directly (e.g. from a bundle), you instead specify settings by putting the JSON directly into the `METEOR_SETTINGS` environment variable. If you don't provide any settings, `Meteor.settings` will be an empty object. If the settings object contains a key named `public`, then `Meteor.settings.public` will be available on the client as well as the server. All other properties of `Meteor.settings` are only defined on the server. * @locus Anywhere + * @type {Object} */ Meteor.settings = { 'public': __meteor_runtime_config__.PUBLIC_SETTINGS }; } diff --git a/packages/meteor/cordova_environment.js b/packages/meteor/cordova_environment.js index 15acdd40740..98f721f5005 100644 --- a/packages/meteor/cordova_environment.js +++ b/packages/meteor/cordova_environment.js @@ -1,5 +1,7 @@ /** * @summary Boolean variable. True if running in a Cordova mobile environment. + * @type {Boolean} + * @static * @locus Anywhere */ Meteor.isCordova = true; diff --git a/packages/meteor/helpers.js b/packages/meteor/helpers.js index 4e91a00bd20..1c4ef94cd17 100644 --- a/packages/meteor/helpers.js +++ b/packages/meteor/helpers.js @@ -6,6 +6,7 @@ if (typeof __meteor_runtime_config__ === 'object' && /** * @summary `Meteor.release` is a string containing the name of the [release](#meteorupdate) with which the project was built (for example, `"1.2.3"`). It is `undefined` if the project was built using a git checkout of Meteor. * @locus Anywhere + * @type {String} */ Meteor.release = __meteor_runtime_config__.meteorRelease; } diff --git a/packages/tracker/tracker.js b/packages/tracker/tracker.js index b9ad4480202..fbbce1551d3 100644 --- a/packages/tracker/tracker.js +++ b/packages/tracker/tracker.js @@ -2,6 +2,10 @@ // Package docs at http://docs.meteor.com/#tracker // ////////////////////////////////////////////////// +/** + * @namespace Tracker + * @summary The namespace for Tracker-related methods. + */ Tracker = {}; // http://docs.meteor.com/#tracker_active @@ -9,6 +13,7 @@ Tracker = {}; /** * @summary True if there is a current computation, meaning that dependencies on reactive data sources will be tracked and potentially cause the current computation to be rerun. * @locus Client + * @type {Boolean} */ Tracker.active = false; @@ -17,6 +22,7 @@ Tracker.active = false; /** * @summary The current computation, or `null` if there isn't one. The current computation is the [`Tracker.Computation`](#tracker_computation) object created by the innermost active call to `Tracker.autorun`, and it's the computation that gains dependencies when reactive data sources are accessed. * @locus Client + * @type {Tracker.Computation} */ Tracker.currentComputation = null; @@ -146,6 +152,7 @@ Tracker.Computation = function (f, parent) { * @memberOf Tracker.Computation * @instance * @name invalidated + * @type {Boolean} */ self.invalidated = false; @@ -157,6 +164,7 @@ Tracker.Computation = function (f, parent) { * @memberOf Tracker.Computation * @instance * @name firstRun + * @type {Boolean} */ self.firstRun = true; @@ -313,6 +321,7 @@ If there is no current computation and `depend()` is called with no arguments, i Returns true if the computation is a new dependent of `dependency` rather than an existing one. * @locus Client * @param {Tracker.Computation} [fromComputation] An optional computation declared to depend on `dependency` instead of the current computation. + * @returns {Boolean} */ Tracker.Dependency.prototype.depend = function (computation) { if (! computation) { @@ -350,6 +359,7 @@ Tracker.Dependency.prototype.changed = function () { /** * @summary True if this Dependency has one or more dependent Computations, which would be invalidated if this Dependency were to change. * @locus Client + * @returns {Boolean} */ Tracker.Dependency.prototype.hasDependents = function () { var self = this; @@ -434,6 +444,7 @@ Tracker.flush = function (_opts) { * @summary Run a function now and rerun it later whenever its dependencies change. Returns a Computation object that can be used to stop or observe the rerunning. * @locus Client * @param {Function} runFunc The function to run. It receives one argument: the Computation object that will be returned. + * @returns {Tracker.Computation} */ Tracker.autorun = function (f) { if (typeof f !== 'function') diff --git a/scripts/admin/jsdoc/jsdoc-conf.json b/scripts/admin/jsdoc/jsdoc-conf.json index 78fe67207df..2d590cd523e 100644 --- a/scripts/admin/jsdoc/jsdoc-conf.json +++ b/scripts/admin/jsdoc/jsdoc-conf.json @@ -16,4 +16,4 @@ "tools/skel-pack/package.js" ] } -} \ No newline at end of file +}