You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@shindig.apache.org by do...@apache.org on 2008/01/25 00:24:26 UTC
svn commit: r615078 - in /incubator/shindig/trunk/features: core/io.js
core/json.js core/prefs.js core/util.js dynamic-height/dynamic-height.js
flash/flash.js minimessage/minimessage.js rpc/rpc.js setprefs/setprefs.js
settitle/settitle.js tabs/tabs.js
Author: doll
Date: Thu Jan 24 15:24:19 2008
New Revision: 615078
URL: http://svn.apache.org/viewvc?rev=615078&view=rev
Log:
Js doc changes that make the shindig js more compatible with jsdoc toolkit generation. No functional changes were introduced.
Note: I did change one doc that actually no longer matches with the coded api. (in flash.js) We need to change the code to reflect the doc asap. I did not make this change now to keep this set of changes small.
Modified:
incubator/shindig/trunk/features/core/io.js
incubator/shindig/trunk/features/core/json.js
incubator/shindig/trunk/features/core/prefs.js
incubator/shindig/trunk/features/core/util.js
incubator/shindig/trunk/features/dynamic-height/dynamic-height.js
incubator/shindig/trunk/features/flash/flash.js
incubator/shindig/trunk/features/minimessage/minimessage.js
incubator/shindig/trunk/features/rpc/rpc.js
incubator/shindig/trunk/features/setprefs/setprefs.js
incubator/shindig/trunk/features/settitle/settitle.js
incubator/shindig/trunk/features/tabs/tabs.js
Modified: incubator/shindig/trunk/features/core/io.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/core/io.js?rev=615078&r1=615077&r2=615078&view=diff
==============================================================================
--- incubator/shindig/trunk/features/core/io.js (original)
+++ incubator/shindig/trunk/features/core/io.js Thu Jan 24 15:24:19 2008
@@ -19,6 +19,12 @@
* Available to every gadget.
*/
+/**
+ * @static
+ * @class Provides remote content retrieval functions.
+ * @name gadgets.io
+ */
+
gadgets.io = function() {
/**
* Holds configuration-related data such as proxy urls.
@@ -163,6 +169,7 @@
* as a placeholder for the actual url.
* - jsonProxyUrl: The url for dynamic proxy requests. Include %url%
* as a placeholder for the actual url.
+ * @private
*/
init : function (configuration) {
config = configuration;
@@ -190,8 +197,6 @@
* defaults to <code>MethodType.GET</a></code>.
* Specified as a
* <a href="gadgets.io.MethodType.html">MethodType</a>.
- *
- * @member gadgets.io.RequestParameters
*/
METHOD : 'METHOD',
@@ -201,8 +206,6 @@
* Specified as a
* <a href="gadgets.io.ContentType.html">
* ContentType</a>.
- *
- * @member gadgets.io.RequestParameters
*/
CONTENT_TYPE : "CONTENT_TYPE",
@@ -210,8 +213,6 @@
* The data to send to the URL using the POST method.
* Specified as a <code>String</code>
* Defaults to null.
- *
- * @member gadgets.io.RequestParameters
*/
POST_DATA : "POST_DATA",
@@ -219,8 +220,6 @@
* The HTTP headers to send to the URL.
* Specified as a <code>Map.<String,String></code>
* Defaults to null.
- *
- * @member gadgets.io.RequestParameters
*/
HEADERS : "HEADERS",
@@ -230,8 +229,6 @@
* Specified as an
* <a href="gadgets.io.AuthorizationType.html">
* AuthorizationType</a>.
- *
- * @member gadgets.io.RequestParameters
*/
AUTHORIZATION : 'AUTHORIZATION',
@@ -240,8 +237,6 @@
* If the content is a feed, the number of entries to fetch;
* defaults to 3.
* Specified as a <code>Number</code>.
- *
- * @member gadgets.io.RequestParameters
*/
NUM_ENTRIES : 'NUM_ENTRIES',
@@ -249,8 +244,6 @@
* If the content is a feed, whether to fetch summaries for that feed;
* defaults to false.
* Specified as a <code>Boolean</code>.
- *
- * @member gadgets.io.RequestParameters
*/
GET_SUMMARIES : 'GET_SUMMARIES'
};
@@ -265,26 +258,25 @@
* @name gadgets.io.MethodType
*/
gadgets.io.MethodType = {
- /** @member gadgets.io.MethodType */
+ /** The default type. */
GET : 'GET',
- /** @member gadgets.io.MethodType */
+ /**
+ * Not supported by all containers.
+ */
POST : 'POST',
/**
- * @member gadgets.io.MethodType
* Not supported by all containers.
*/
PUT : 'PUT',
/**
- * @member gadgets.io.MethodType
* Not supported by all containers.
*/
DELETE : 'DELETE',
/**
- * @member gadgets.io.MethodType
* Not supported by all containers.
*/
HEAD : 'HEAD'
@@ -302,25 +294,21 @@
gadgets.io.ContentType = {
/**
* Returns text, used for fetching html.
- * @member gadgets.io.ContentType
*/
TEXT : 'TEXT',
/**
* Returns a dom object, used for fetching xml.
- * @member gadgets.io.ContentType
*/
DOM : 'DOM',
/**
* Returns a json object.
- * @member gadgets.io.ContentType
*/
JSON : 'JSON',
/**
* Returns a json representation of a feed.
- * @member gadgets.io.ContentType
*/
FEED : 'FEED'
};
@@ -335,12 +323,12 @@
* @name gadgets.io.AuthorizationType
*/
gadgets.io.AuthorizationType = {
- /** @member gadgets.io.AuthorizationType */
+ /** No authorization */
NONE : 'NONE',
- /** @member gadgets.io.AuthorizationType */
+ /** The request will be signed by the container */
SIGNED : 'SIGNED',
- /** @member gadgets.io.AuthorizationType */
+ /** The container will use full authentication */
AUTHENTICATED : 'AUTHENTICATED'
};
Modified: incubator/shindig/trunk/features/core/json.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/core/json.js?rev=615078&r1=615077&r2=615078&view=diff
==============================================================================
--- incubator/shindig/trunk/features/core/json.js (original)
+++ incubator/shindig/trunk/features/core/json.js Thu Jan 24 15:24:19 2008
@@ -21,19 +21,25 @@
/**
* @fileoverview
- * The global object JSON contains two methods.
+ * The global object gadgets.json contains two methods.
*
- * JSON.stringify(value) takes a JavaScript value and produces a JSON text.
- * The value must not be cyclical.
+ * gadgets.json.stringify(value) takes a JavaScript value and produces a JSON
+ * text. The value must not be cyclical.
*
- * JSON.parse(text) takes a JSON text and produces a JavaScript value. It will
- * return false if there is an error.
+ * gadgets.json.parse(text) takes a JSON text and produces a JavaScript value.
+ * It will return false if there is an error.
*/
var gadgets = gadgets || {};
/**
- * @scope gadgets.JSON
+ * @static
+ * @class Provides operations for translating objects to and from JSON.
+ * @name gadgets.json
+ */
+
+/**
+ * @scope gadgets.json
*/
gadgets.json = function () {
var m = {
@@ -160,5 +166,5 @@
};
}();
-var JSON = gadgets.JSON;
+var JSON = gadgets.json;
Modified: incubator/shindig/trunk/features/core/prefs.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/core/prefs.js?rev=615078&r1=615077&r2=615078&view=diff
==============================================================================
--- incubator/shindig/trunk/features/core/prefs.js (original)
+++ incubator/shindig/trunk/features/core/prefs.js Thu Jan 24 15:24:19 2008
@@ -155,14 +155,18 @@
}();
/**
- * @constructor
- * @param {String | Number} moduleId The module id to create prefs for.
+ * @class A class gadgets can use to get user preference information.
+ *
+ * @description Creates a new Prefs object
+ * @param {String | Number} opt_moduleId An optional parameters specifying the
+ * module id to create prefs for. If not provided, the default module id
+ * will be used.
*/
-gadgets.Prefs = function(moduleId) {
- if (typeof moduleId === "undefined") {
+gadgets.Prefs = function(opt_moduleId) {
+ if (typeof opt_moduleId === "undefined") {
this.moduleId_ = gadgets.prefs_.getDefaultModuleId();
} else {
- this.moduleId_ = moduleId;
+ this.moduleId_ = opt_moduleId;
}
this.data_ = gadgets.prefs_.getModuleData(this.moduleId_);
// This is used to eliminate one hash table lookup per value fetched.
Modified: incubator/shindig/trunk/features/core/util.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/core/util.js?rev=615078&r1=615077&r2=615078&view=diff
==============================================================================
--- incubator/shindig/trunk/features/core/util.js (original)
+++ incubator/shindig/trunk/features/core/util.js Thu Jan 24 15:24:19 2008
@@ -17,6 +17,13 @@
/**
* @fileoverview General purpose utilities that gadgets can use.
*/
+
+/**
+ * @static
+ * @class Provides general purpose utility functions.
+ * @name gadgets.util
+ */
+
gadgets.util = function() {
/**
* Parses url parameters into an object.
Modified: incubator/shindig/trunk/features/dynamic-height/dynamic-height.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/dynamic-height/dynamic-height.js?rev=615078&r1=615077&r2=615078&view=diff
==============================================================================
--- incubator/shindig/trunk/features/dynamic-height/dynamic-height.js (original)
+++ incubator/shindig/trunk/features/dynamic-height/dynamic-height.js Thu Jan 24 15:24:19 2008
@@ -22,11 +22,19 @@
*/
var gadgets = gadgets || {};
+
+/**
+ * @static
+ * @class Provides operations for getting information about and modifying the
+ * window the gadget is placed in.
+ * @name gadgets.window
+ */
gadgets.window = gadgets.window || {};
/**
* Detects the inner dimensions of a frame.
- * See: http://www.quirksmode.org/viewport/compatibility.html
+ * See: http://www.quirksmode.org/viewport/compatibility.html for more
+ * information.
* @returns {Object} An object with width and height properties.
*/
gadgets.window.getViewportDimensions = function() {
@@ -53,7 +61,8 @@
/**
* Adjusts the gadget height
- * @param {Number} opt_height Preferred height in pixels.
+ * @param {Number} opt_height An optional preferred height in pixels. If not
+ * specified, will attempt to fit the gadget to its content.
*/
gadgets.window.adjustHeight = function(opt_height) {
var newHeight = parseInt(opt_height, 10);
Modified: incubator/shindig/trunk/features/flash/flash.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/flash/flash.js?rev=615078&r1=615077&r2=615078&view=diff
==============================================================================
--- incubator/shindig/trunk/features/flash/flash.js (original)
+++ incubator/shindig/trunk/features/flash/flash.js Thu Jan 24 15:24:19 2008
@@ -22,6 +22,12 @@
*/
var gadgets = gadgets || {};
+
+/**
+ * @static
+ * @class Embeds Flash content in gadgets.
+ * @name gadgets.flash
+ */
gadgets.flash = gadgets.flash || {};
/**
@@ -55,22 +61,15 @@
/**
* Injects a Flash file into the DOM tree.
* @param {String} swfUrl SWF URL.
- * @param {String|Object} swfContainer The id or object reference of an existing
- * html container element.
- * @param {Object} opt_params An optional object that may contain one or more
- * fields:
- * {Number} .swf_version
- * Minimal Flash Player version required.
- * {Number|String} .width, .height
- * Preferred width and height. (Default value: '100%')
- * {String} .base
- * The base attribute enforces the base location from which the URL
- * loads. This prevents confusion about the location to which relative
- * links are relative. (Default value: the path of swfUrl)
- * Other fields such as .quality and .id can also be defined and will be
- * passed to the Flash movie on creation. The values must be HTML-escaped.
+ * @param {String | Object} swfContainer The id or object reference of an
+ * existing html container element.
+ * @param {Number} swfVersion Minimal Flash Player version required.
+ * @param {Object} opt_params An optional object that may contain any valid html
+ * parameter. All attributes will be passed through to the flash movie on
+ * creation.
* @return {Boolean} Whether the function call completes successfully.
*/
+// TODO The shindig implementation does not match the spec described above!
gadgets.flash.embedFlash = function(swfUrl, swfContainer, opt_params) {
switch (typeof swfContainer) {
case 'string':
Modified: incubator/shindig/trunk/features/minimessage/minimessage.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/minimessage/minimessage.js?rev=615078&r1=615077&r2=615078&view=diff
==============================================================================
--- incubator/shindig/trunk/features/minimessage/minimessage.js (original)
+++ incubator/shindig/trunk/features/minimessage/minimessage.js Thu Jan 24 15:24:19 2008
@@ -19,19 +19,23 @@
/**
* @fileoverview Library for creating small dismissible messages in gadgets.
* Typical use cases:
- * - status messages, e.g. loading, saving, etc.
- * - promotional messages, e.g. new features, new gadget, etc.
- * - debug/error messages, e.g. bad input, failed connection to server
+ * <ul>
+ * <li> status messages, e.g. loading, saving, etc.
+ * <li> promotional messages, e.g. new features, new gadget, etc.
+ * <li> debug/error messages, e.g. bad input, failed connection to server
+ * </ul>
*/
var gadgets = gadgets || {};
/**
- * MiniMessage class.
- * @param {string} opt_moduleId Optional module Id.
+ * @class MiniMessage class.
+ *
+ * @description Used to create messages that will appear to the user within the
+ * gadget.
+ * @param {String} opt_moduleId Optional module Id.
* @param {Element} opt_container Optional HTML container element where
* mini-messages will appear.
- * @constructor
*/
gadgets.MiniMessage = function(opt_moduleId, opt_container) {
this.numMessages_ = 0;
@@ -44,6 +48,7 @@
* Helper function that creates a container HTML element where mini-messages
* will be appended to. The container element is inserted at the top of gadget.
* @return {Element} An HTML div element as the message container.
+ * @private
*/
gadgets.MiniMessage.prototype.createContainer_ = function() {
var containerId = 'mm_' + this.moduleId_;
@@ -61,7 +66,8 @@
/**
* Helper function that dynamically inserts CSS rules to the page.
- * @param {string} cssText CSS rules to inject.
+ * @param {String} cssText CSS rules to inject.
+ * @private
*/
gadgets.MiniMessage.addCSS_ = function(cssText) {
var head = document.getElementsByTagName('head')[0];
@@ -79,8 +85,9 @@
/**
* Helper function that expands a class name into two class names.
- * @param {string} label The CSS class name.
- * @return {string} "X Xn", with n is the ID of this module.
+ * @param {String} label The CSS class name.
+ * @return {String} "X Xn", with n is the ID of this module.
+ * @private
*/
gadgets.MiniMessage.prototype.cascade_ = function(label) {
return label + ' ' + label + this.moduleId_;
@@ -94,6 +101,7 @@
* @param {Function} opt_callback Optional callback function to be called when
* the message is dismissed.
* @return {Function} A function that dismisses the specified message.
+ * @private
*/
gadgets.MiniMessage.prototype.dismissFunction_ = function(element, opt_callback) {
return function() {
@@ -112,7 +120,7 @@
* Creates a dismissible message with an [x] icon allowing users to dismiss
* the message. When the message is dismissed, it is removed from the DOM,
* and the optional callback function is called, if defined.
- * @param {string | Object} message The message as an HTML string or DOM element.
+ * @param {String | Object} message The message as an HTML string or DOM element.
* @param {Function} opt_callback Optional callback function to be called when
* the message is dismissed.
* @return {Element} HTML element of the created message.
@@ -136,7 +144,7 @@
/**
* Creates a timer message that displays for x seconds. When the timer expires,
* the message is dismissed, and the optional callback function is executed.
- * @param {string | Object} message The message as an HTML string or DOM element.
+ * @param {String | Object} message The message as an HTML string or DOM element.
* @param {number} seconds Number of seconds to wait before dismissing
* the message.
* @param {Function} opt_callback Optional callback function to be called when
@@ -153,7 +161,7 @@
/**
* Creates a static message that can only be dismissed programmatically
* by calling dismissMessage().
- * @param {string | Object} message The message as an HTML string or DOM element.
+ * @param {String | Object} message The message as an HTML string or DOM element.
* @return {Element} HTML element of the created message.
*/
gadgets.MiniMessage.prototype.createStaticMessage = function(message) {
Modified: incubator/shindig/trunk/features/rpc/rpc.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/rpc/rpc.js?rev=615078&r1=615077&r2=615078&view=diff
==============================================================================
--- incubator/shindig/trunk/features/rpc/rpc.js (original)
+++ incubator/shindig/trunk/features/rpc/rpc.js Thu Jan 24 15:24:19 2008
@@ -23,11 +23,16 @@
var gadgets = gadgets || {};
+/**
+ * @static
+ * @class Provides operations for making rpc calls.
+ * @name gadgets.rpc
+ */
gadgets.rpc = function() {
- return {
+ return /** @scope gadgets.rpc */ {
/**
* Registers an RPC service.
- * @param {string} serviceName Service name to register.
+ * @param {String} serviceName Service name to register.
* @param {Function} handler Service handler.
*/
register: function(serviceName, handler) {
@@ -36,7 +41,7 @@
/**
* Unregisters an RPC service.
- * @param {string} serviceName Service name to unregister.
+ * @param {String} serviceName Service name to unregister.
*/
unregister: function(serviceName) {
// TODO
@@ -61,9 +66,9 @@
/**
* Calls an RPC service.
- * @param {string} targetId Id of the RPC service provider.
+ * @param {String} targetId Id of the RPC service provider.
* Empty if calling the parent container.
- * @param {string} serviceName Service name to call.
+ * @param {String} serviceName Service name to call.
* @param {Function|null} callback Callback function (if any) to process
* the return value of the RPC request.
* @param {*} var_args Parameters for the RPC request.
Modified: incubator/shindig/trunk/features/setprefs/setprefs.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/setprefs/setprefs.js?rev=615078&r1=615077&r2=615078&view=diff
==============================================================================
--- incubator/shindig/trunk/features/setprefs/setprefs.js (original)
+++ incubator/shindig/trunk/features/setprefs/setprefs.js Thu Jan 24 15:24:19 2008
@@ -25,6 +25,7 @@
* Stores a preference.
* @param {String | Object} key The pref to store.
* @param {String} val The values to store.
+ * @private This feature is documented in prefs.js
*/
gadgets.Prefs.prototype.set = function(key, value) {
if (arguments.length > 2) {
@@ -54,6 +55,7 @@
* Stores a preference from the given list.
* @param {String} key The pref to store.
* @param {Array.<String | Number>} val The values to store.
+ * @private This feature is documented in prefs.js
*/
gadgets.Prefs.prototype.setArray = function(key, val) {
if (!val.length || !val.join) {
Modified: incubator/shindig/trunk/features/settitle/settitle.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/settitle/settitle.js?rev=615078&r1=615077&r2=615078&view=diff
==============================================================================
--- incubator/shindig/trunk/features/settitle/settitle.js (original)
+++ incubator/shindig/trunk/features/settitle/settitle.js Thu Jan 24 15:24:19 2008
@@ -22,11 +22,18 @@
*/
var gadgets = gadgets || {};
+
+/**
+ * @static
+ * @class Provides operations for getting information about and modifying the
+ * window the gadget is placed in.
+ * @name gadgets.window
+ */
gadgets.window = gadgets.window || {};
/**
* Sets the gadget title.
- * @param {String} title Preferred title.
+ * @param {String} title The preferred title.
*/
gadgets.window.setTitle = function(title) {
var modId = 'remote_module_' + (new gadgets.Prefs()).getModuleId();
Modified: incubator/shindig/trunk/features/tabs/tabs.js
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/features/tabs/tabs.js?rev=615078&r1=615077&r2=615078&view=diff
==============================================================================
--- incubator/shindig/trunk/features/tabs/tabs.js (original)
+++ incubator/shindig/trunk/features/tabs/tabs.js Thu Jan 24 15:24:19 2008
@@ -23,16 +23,17 @@
var gadgets = gadgets || {};
/**
- * Tabs class.
- * @param {string} opt_moduleId Optional suffix for the ID of tab container.
- * @param {string} opt_defaultTab Optional tab name that specifies the name of
+ * @class A class gadgets can use to make tabs.
+ * @description Creates a new Tabs object
+ *
+ * @param {String} opt_moduleId Optional suffix for the ID of tab container.
+ * @param {String} opt_defaultTab Optional tab name that specifies the name of
* of the tab that is selected after initialization.
* If this parameter is omitted, the first tab is selected by
* default.
* @param {Element} opt_container The HTML element to contain the tabs. If
* omitted, a new div element is created and inserted at the
* very top.
- * @constructor
*/
gadgets.Tabs = function(opt_moduleId, opt_defaultTab, opt_container) {
// TODO
@@ -40,7 +41,7 @@
/**
* Adds a new tab based on the name-value pairs specified in opt_params.
- * @param {string} tabName Label of the tab to create.
+ * @param {String} tabName Label of the tab to create.
* @param {Object} opt_params Optional parameter object. The following
* properties are supported:
* .contentContainer An existing HTML element to be used as
@@ -52,7 +53,7 @@
* the mouse cursor over the tab.
* .index The index at which to insert the tab. If omitted,
* the new tab is appended to the end.
- * @return {string} DOM id of the tab container.
+ * @return {String} DOM id of the tab container.
*/
gadgets.Tabs.prototype.addTab = function(tabName, opt_params) {
// TODO
@@ -60,7 +61,7 @@
/**
* Removes a tab at tabIndex and all of its associated content.
- * @param {number} tabIndex Index of the tab to remove.
+ * @param {Number} tabIndex Index of the tab to remove.
*/
gadgets.Tabs.prototype.removeTab = function(tabIndex) {
// TODO
@@ -77,7 +78,7 @@
/**
* Selects the tab at tabIndex and fires the tab's callback function if it
* exists. If the tab is already selected, the callback is not fired.
- * @param {number} tabIndex Index of the tab to select.
+ * @param {Number} tabIndex Index of the tab to select.
*/
gadgets.Tabs.prototype.setSelectedTab = function(tabIndex) {
// TODO
@@ -86,8 +87,8 @@
/**
* Swaps the positions of tabs at tabIndex1 and tabIndex2. The selected tab
* does not change, and no callback functions are called.
- * @param {number} tabIndex1 Index of the first tab to swap.
- * @param {number} tabIndex2 Index of the secnod tab to swap.
+ * @param {Number} tabIndex1 Index of the first tab to swap.
+ * @param {Number} tabIndex2 Index of the secnod tab to swap.
*/
gadgets.Tabs.prototype.swapTabs = function(tabIndex1, tabIndex2) {
// TODO
@@ -104,8 +105,8 @@
/**
* Sets the alignment of tabs. Tabs are center-aligned by default.
- * @param {string} align 'left', 'center', or 'right'.
- * @param {number} opt_offset Optional parameter to set the number of pixels
+ * @param {String} align 'left', 'center', or 'right'.
+ * @param {Number} opt_offset Optional parameter to set the number of pixels
* to offset tabs from the left or right edge. The default
* value is 3px.
*/
@@ -115,7 +116,7 @@
/**
* Shows or hides tabs and all associated content.
- * @param {boolean} display true to show tabs; false to hide tabs.
+ * @param {Boolean} display true to show tabs; false to hide tabs.
*/
gadgets.Tabs.prototype.displayTabs = function(display) {
// TODO