From 5a29866a48da7a3ae5bd30919ce78fe3a59408f2 Mon Sep 17 00:00:00 2001 From: Jack Allnutt Date: Thu, 20 Oct 2011 17:48:05 +0100 Subject: [PATCH] Adding JSDoc documentation to clientside JS files --- client/js/front.events.js | 166 ++++++++++++++++++++++++++++- client/js/front.js | 219 ++++++++++++++++++++++++++++++++++---- client/js/front.ui.js | 56 ++++++++-- client/js/gateway.js | 129 +++++++++++++++++++++- client/js/util.js | 62 +++++++++-- 5 files changed, 590 insertions(+), 42 deletions(-) diff --git a/client/js/front.events.js b/client/js/front.events.js index d4b8dfc..81e5db0 100644 --- a/client/js/front.events.js +++ b/client/js/front.events.js @@ -1,7 +1,13 @@ /*jslint browser: true, devel: true, sloppy: true, plusplus: true, nomen: true, forin: true, continue: true */ /*globals kiwi, $, _, Tabview, Userlist, User, Box, init_data */ +/** +* @namespace +*/ kiwi.front.events = { + /** + * Binds all of the event handlers to their events + */ bindAll: function () { $(kiwi.gateway).bind("onmsg", this.onMsg); $(kiwi.gateway).bind("onnotice", this.onNotice); @@ -36,7 +42,11 @@ kiwi.front.events = { $(kiwi.gateway).bind("onkiwi", this.onKiwi); }, - + /** + * Handles the msg event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onMsg: function (e, data) { var destination, plugin_event, tab; // Is this message from a user? @@ -58,6 +68,11 @@ kiwi.front.events = { tab.addMsg(null, plugin_event.nick, plugin_event.msg); }, + /** + * Handles the debug event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onDebug: function (e, data) { var tab = Tabview.getTab('kiwi_debug'); if (!tab) { @@ -66,6 +81,11 @@ kiwi.front.events = { tab.addMsg(null, ' ', data.msg); }, + /** + * Handles the action event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onAction: function (e, data) { var destination, tab; // Is this message from a user? @@ -82,6 +102,11 @@ kiwi.front.events = { tab.addMsg(null, ' ', '* ' + data.nick + ' ' + data.msg, 'action', 'color:#555;'); }, + /** + * Handles the topic event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onTopic: function (e, data) { var tab = Tabview.getTab(data.channel); if (tab) { @@ -89,6 +114,11 @@ kiwi.front.events = { } }, + /** + * Handles the notice event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onNotice: function (e, data) { var nick = (data.nick === undefined) ? '' : data.nick, enick = '[' + nick + ']'; @@ -102,6 +132,11 @@ kiwi.front.events = { } }, + /** + * Handles the CTCP request event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onCTCPRequest: function (e, data) { var msg = data.msg.split(" ", 2); switch (msg[0]) { @@ -118,14 +153,29 @@ kiwi.front.events = { Tabview.getServerTab().addMsg(null, 'CTCP Request', '[from ' + data.nick + '] ' + data.msg, 'ctcp'); }, + /** + * Handles the CTCP response event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onCTCPResponse: function (e, data) { Tabview.getServerTab().addMsg(null, 'CTCP Reply', '[from ' + data.nick + '] ' + data.msg, 'ctcp'); }, + /** + * Handles the kiwi event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onKiwi: function (e, data) { //console.log(data); }, + /** + * Handles the connect event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onConnect: function (e, data) { var err_box, channels; @@ -169,11 +219,21 @@ kiwi.front.events = { return "Are you sure you leave Kiwi IRC?"; }; }, + /** + * Handles the connectFail event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onConnectFail: function (e, data) { var reason = (typeof data.reason === 'string') ? data.reason : ''; Tabview.getServerTab().addMsg(null, '', 'There\'s a problem connecting! (' + reason + ')', 'error'); kiwi.plugs.run('connect', {success: false}); }, + /** + * Handles the disconnect event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onDisconnect: function (e, data) { var tab, tabs; tabs = Tabview.getAllTabs(); @@ -182,6 +242,11 @@ kiwi.front.events = { } kiwi.plugs.run('disconnect', {success: false}); }, + /** + * Handles the reconnecting event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onReconnecting: function (e, data) { var err_box, f, msg, mins, secs; @@ -190,6 +255,9 @@ kiwi.front.events = { return; } + /** + * @inner + */ f = function (num) { switch (num) { case 1: return 'First'; @@ -214,14 +282,29 @@ kiwi.front.events = { err_box.text(msg); }, + /** + * Handles the options event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onOptions: function (e, data) { if (typeof kiwi.gateway.network_name === "string" && kiwi.gateway.network_name !== "") { Tabview.getServerTab().setTabText(kiwi.gateway.network_name); } }, + /** + * Handles the MOTD event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onMOTD: function (e, data) { Tabview.getServerTab().addMsg(null, data.server, data.msg, 'motd'); }, + /** + * Handles the whois event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onWhois: function (e, data) { /*globals secondsToTime */ var d, tab, idle_time = ''; @@ -248,6 +331,11 @@ kiwi.front.events = { tab.addMsg(null, data.nick, 'idle for ' + idle_time, 'whois'); } }, + /** + * Handles the mode event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onMode: function (e, data) { var tab; if ((typeof data.channel === 'string') && (typeof data.effected_nick === 'string')) { @@ -260,6 +348,11 @@ kiwi.front.events = { // TODO: Other mode changes that aren't +/- qaohv. - JA }, + /** + * Handles the userList event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onUserList: function (e, data) { var tab; @@ -280,6 +373,11 @@ kiwi.front.events = { tab.userlist.addUser(data.users); }, + /** + * Handles the userListEnd event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onUserListEnd: function (e, data) { if (!kiwi.front.cache.userlist) { kiwi.front.cache.userlist = {}; @@ -287,25 +385,55 @@ kiwi.front.events = { kiwi.front.cache.userlist.updating = false; }, + /** + * Handles the channelListStart event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onChannelListStart: function (e, data) { /*global ChannelList */ kiwi.front.cache.list = new ChannelList(); console.profile('list'); }, + /** + * Handles the channelList event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onChannelList: function (e, data) { kiwi.front.cache.list.addChannel(data.chans); }, + /** + * Handles the channelListEnd event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onChannelListEnd: function (e, data) { kiwi.front.cache.list.show(); console.profileEnd(); }, + /** + * Handles the banList event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onBanList: function (e, data) { }, + /** + * Handles the banListEnd event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onBanListEnd: function (e, data) { }, + /** + * Handles the join event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onJoin: function (e, data) { var tab = Tabview.getTab(data.channel); if (!tab) { @@ -320,6 +448,11 @@ kiwi.front.events = { tab.userlist.addUser({nick: data.nick, modes: []}); }, + /** + * Handles the part event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onPart: function (e, data) { var tab = Tabview.getTab(data.channel); if (tab) { @@ -334,6 +467,11 @@ kiwi.front.events = { tab.userlist.removeUser(data.nick); } }, + /** + * Handles the kick event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onKick: function (e, data) { var tab = Tabview.getTab(data.channel); if (tab) { @@ -350,6 +488,11 @@ kiwi.front.events = { tab.userlist.removeUser(data.nick); } }, + /** + * Handles the nick event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onNick: function (e, data) { if (data.nick === kiwi.gateway.nick) { kiwi.gateway.nick = data.newnick; @@ -363,6 +506,11 @@ kiwi.front.events = { } }); }, + /** + * Handles the quit event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onQuit: function (e, data) { _.each(Tabview.getAllTabs(), function (tab) { if (tab.userlist.hasUser(data.nick)) { @@ -371,6 +519,11 @@ kiwi.front.events = { } }); }, + /** + * Handles the channelRedirect event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onChannelRedirect: function (e, data) { var tab = Tabview.getTab(data.from); tab.close(); @@ -378,6 +531,11 @@ kiwi.front.events = { tab.addMsg(null, ' ', '=== Redirected from ' + data.from, 'action'); }, + /** + * Handles the IRCError event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onIRCError: function (e, data) { var t_view, tab = Tabview.getTab(data.channel); @@ -435,7 +593,11 @@ kiwi.front.events = { - + /** + * Handles the sync event + * @param {eventObject} e The event object + * @param {Object} data The event data + */ onSync: function (e, data) { // Set any settings if (data.nick !== undefined) { diff --git a/client/js/front.js b/client/js/front.js index f08cc50..a59aa90 100644 --- a/client/js/front.js +++ b/client/js/front.js @@ -1,18 +1,55 @@ /*jslint white:true, regexp: true, nomen: true, devel: true, undef: true, browser: true, continue: true, sloppy: true, forin: true, newcap: true, plusplus: true, maxerr: 50, indent: 4 */ /*global kiwi, _, io, $, iScroll, agent, touchscreen, init_data, plugs, plugins, registerTouches, randomString */ +/** +* @namespace +*/ kiwi.front = { - cur_channel: '', + /** + * The current channel + * @type Object + */ + cur_channel: null, + /** + * A list of windows + * @type Object + */ windows: {}, + /** + * A list of Tabviews + * @type Object + */ tabviews: {}, + /** + * A list of Utilityviews + * @type Object + */ utilityviews: {}, + /** + * A list of Boxes + * @type Object + */ boxes: {}, - buffer: [], // Command history - buffer_pos: 0, // Current command history position - - // Container for misc data (eg. userlist generation) + /** + * The command history + * @type Array + */ + buffer: [], + /** + * The current command history position + * @type Number + */ + buffer_pos: 0, + + /** + * Container for misc data (eg. userlist generation) + * @type Object + */ cache: {original_topic: '', userlist: {}}, + /** + * Initialisation function + */ init: function () { /*global Box, touch_scroll:true, Tabview */ var about_info, supportsOrientationChange, orientationEvent, scroll_opts, server_tabview; @@ -100,8 +137,12 @@ kiwi.front = { $('#kiwi .connectwindow').slideUp('', kiwi.front.ui.barsShow); - // Listen for keyboard activity on any window, and forward it to the - // input box so users can type even if the input box is not in focus + /** + * Listen for keyboard activity on any window, and forward it to the + * input box so users can type even if the input box is not in focus + * @inner + * @param {eventObject} event The event to forward + */ forwardKeys = function (event) { $('#kiwi_msginput').focus(); $('#kiwi_msginput').trigger(event); @@ -203,7 +244,10 @@ kiwi.front = { - + /** + * Joins a channel + * @param {String} chan_name The name of the channel to join + */ joinChannel: function (chan_name) { var chans = chan_name.split(','), i, @@ -221,7 +265,10 @@ kiwi.front = { } }, - + /** + * Parses and executes text and commands entered into the input msg box + * @param {String} msg The message string to parse + */ run: function (msg) { var parts, dest, t, pos, textRange, plugin_event, msg_sliced, tab, nick; @@ -414,11 +461,19 @@ kiwi.front = { - + /** + * Syncs with the Kiwi server + * Not implemented + */ sync: function () { kiwi.gateway.sync(); }, + /** + * Checks if a given name is the name of a channel + * @param {String} name The name to check + * @returns {Boolean} True if name is the name of a channel, false if it is not + */ isChannel: function (name) { var prefix, is_chan; prefix = name.charAt(0); @@ -431,6 +486,11 @@ kiwi.front = { return is_chan; }, + /** + * Formats a message. Adds bold, underline and colouring + * @param {String} msg The message to format + * @returns {String} The HTML formatted message + */ formatIRCMsg: function (msg) { var re, next; @@ -463,13 +523,22 @@ kiwi.front = { } // colour + /** + * @inner + */ msg = (function (msg) { var replace, colourMatch, col, i, match, to, endCol, fg, bg, str; replace = ''; + /** + * @inner + */ colourMatch = function (str) { var re = /^\x03([0-9][0-5]?)(,([0-9][0-5]?))?/; return re.exec(str); }; + /** + * @inner + */ col = function (num) { switch (parseInt(num, 10)) { case 0: @@ -512,6 +581,9 @@ kiwi.front = { i = msg.indexOf('\x03'); replace = msg.substr(0, i); while (i < msg.length) { + /** + * @inner + */ match = colourMatch(msg.substr(i, 6)); if (match) { //console.log(match); @@ -549,7 +621,10 @@ kiwi.front = { return msg; }, - + + /** + * Registers Kiwi IRC as a handler for the irc:// protocol in the browser + */ registerProtocolHandler: function () { var state, uri; url = kiwi_server.replace(/\/kiwi$/, '/?ircuri=%s'); @@ -570,7 +645,9 @@ kiwi.front = { - +/** +* @constructor +*/ var ChannelList = function () { /*globals Utilityview */ var chanList, view, table, obj, renderTable, waiting; @@ -583,6 +660,9 @@ var ChannelList = function () { table = table.appendTo(view.div); waiting = false; + /** + * @inner + */ renderTable = function () { var tbody; tbody = table.children('tbody:first').detach(); @@ -603,8 +683,14 @@ var ChannelList = function () { table = table.append(tbody); waiting = false; }; - - obj = { + /** + * @lends ChannelList + */ + return { + /** + * Adds a channel or channels to the list + * @param {Object} channels The channel or Array of channels to add + */ addChannel: function (channels) { if (!_.isArray(channels)) { channels = [channels]; @@ -623,16 +709,24 @@ var ChannelList = function () { _.defer(renderTable); } }, + /** + * Show the {@link UtilityView} that will display this channel list + */ show: function () { view.show(); }, + /** + * @private + */ prototype: {constructor: this} }; - return obj; }; - +/** +* @constructor +* @param {String} name The name of the UserList +*/ var UserList = function (name) { /*globals User */ var userlist, list_html, sortUsers; @@ -643,6 +737,9 @@ var UserList = function (name) { list_html = $('#kiwi_userlist_' + name); $('a.nick', list_html[0]).live('click', this.clickHandler); + /** + * @inner + */ sortUsers = function () { var parent; parent = list_html.parent(); @@ -672,6 +769,12 @@ var UserList = function (name) { list_html = list_html.appendTo(parent); }; + /** + * Adds a user or users to the UserList. + * Chainable method. + * @param {Object} users The user or Array of users to add + * @returns {UserList} This UserList + */ this.addUser = function (users) { if (!_.isArray(users)) { users = [users]; @@ -687,6 +790,12 @@ var UserList = function (name) { return this; }; + /** + * Removes a user or users from the UserList. + * Chainable method. + * @param {String} nicks The nick or Array of nicks to remove + * @returns {UserList} This UserList + */ this.removeUser = function (nicks) { var toRemove; if (!_.isArray(nicks)) { @@ -707,6 +816,13 @@ var UserList = function (name) { return this; }; + /** + * Renames a user in the UserList. + * Chainable method. + * @param {String} oldNick The old nick + * @param {String} newNick The new nick + * @returns {UserList} This UserList + */ this.renameUser = function (oldNick, newNick) { var user = _.detect(userlist, function (u) { return u.nick === oldNick; @@ -721,6 +837,12 @@ var UserList = function (name) { return this; }; + /** + * Lists the users in this UserList. + * @param {Boolean} modesort True to enable sorting by mode, false for lexicographical sort + * @param {Array} mode If specified, only return those users who have the specified modes + * @returns {Array} The users in the UserList that match the criteria + */ this.listUsers = function (modesort, modes) { var users = userlist; if (modes) { @@ -741,12 +863,20 @@ var UserList = function (name) { } }; + /** + * Remove this UserList from the DOM. + */ this.remove = function () { list_html.remove(); list_html = null; userlist = null; }; + /** + * Empty the UserList. + * Chainable method. + * @returns {UserList} This UserList + */ this.empty = function () { list_html.children().remove(); userlist = []; @@ -754,12 +884,22 @@ var UserList = function (name) { return this; }; + /** + * Checks whether a given nick is in the UserList. + * @param {String} nick The nick to search for + * @returns {Boolean} True if the nick is in the userlist, false otherwise + */ this.hasUser = function (nick) { return _.any(userlist, function (user) { return user.nick === nick; }); }; + /** + * Returns the object representing the user with the given nick, if it is in the UserList. + * @param {String} nick The nick to retrieve + * @returns {Object} An object representing the user, if it exists, null otherwise + */ this.getUser = function (nick) { if (this.hasUser(nick)) { return _.detect(userlist, function (user) { @@ -770,6 +910,12 @@ var UserList = function (name) { } }; + /** + * Sets the UserList's activity. + * Chainable method. + * @param {Boolean} active If true, sets the UserList to active. If False, sets it to inactive + * @returns {UserList} This UserList + */ this.active = function (active) { if ((arguments.length === 0) || (active)) { list_html.addClass('active'); @@ -782,6 +928,14 @@ var UserList = function (name) { return this; }; + /** + * Updates a user's mode. + * Chainable method. + * @param {String} nick The nick of the user to modify + * @param {String} mode The mode to add or remove + * @param {Boolean} add Adds the mode if true, removes it otherwise + * @returns {UserList} This UserList + */ this.changeUserMode = function (nick, mode, add) { var user, prefix; if (this.hasUser(nick)) { @@ -804,7 +958,16 @@ var UserList = function (name) { return this; }; }; +/** +* @memberOf UserList +*/ UserList.prototype.width = 100; // 0 to disable +/** +* Sets the width of the UserList. +* Chainable method. +* @param {Number} newWidth The new width of the UserList +* @returns {UserList} This UserList +*/ UserList.prototype.setWidth = function (newWidth) { var w, u; if (typeof newWidth === 'number') { @@ -818,7 +981,9 @@ UserList.prototype.setWidth = function (newWidth) { return this; }; - +/** +* The click handler for this UserList +*/ UserList.prototype.clickHandler = function () { var li = $(this).parent(), user = li.data('user'); @@ -846,10 +1011,14 @@ UserList.prototype.clickHandler = function () { - +/** +* @constructor +*/ var User = function (nick, modes) { var sortModes; - + /** + * @inner + */ sortModes = function (modes) { return modes.sort(function (a, b) { var a_idx, b_idx, i; @@ -975,7 +1144,9 @@ User.compare = function (a, b) { /* * MISC VIEW */ - +/** +* @constructor +*/ var Utilityview = function (name) { var rand_name = randomString(15), tmp_divname = 'kiwi_window_' + rand_name, @@ -1082,7 +1253,9 @@ Utilityview.prototype.clearPartImage = function () { * */ - +/** +* @constructor +*/ var Tabview = function (v_name) { /*global Tabview, UserList */ var re, htmlsafe_name, tmp_divname, tmp_userlistname, tmp_tabname, tmp_tab, userlist_enabled = true; @@ -1352,7 +1525,9 @@ Tabview.getCurrentTab = function () { - +/** +* @constructor +*/ var Box = function (classname) { this.id = randomString(10); var tmp = $('
'); diff --git a/client/js/front.ui.js b/client/js/front.ui.js index 6b0d901..bd4a017 100644 --- a/client/js/front.ui.js +++ b/client/js/front.ui.js @@ -1,7 +1,13 @@ /*jslint browser: true, devel: true, sloppy: true, plusplus: true, nomen: true, forin: true, continue: true */ /*globals kiwi, $, _, Tabview, Userlist, User, Box */ +/** +* @namespace +*/ kiwi.front.ui = { + /** + * + */ doLayoutSize: function () { var kiwi, toolbars, ul, n_top, n_bottom, nl; kiwi = $('#kiwi'); @@ -28,14 +34,18 @@ kiwi.front.ui = { nl.css({top: n_top + 'px', bottom: n_bottom + 'px', left: $(document).width() - ul.outerWidth(true)}); }, - + /** + * + */ doLayout: function () { $('#kiwi .msginput .nick a').text(kiwi.gateway.nick); $('#kiwi_msginput').val(' '); $('#kiwi_msginput').focus(); }, - + /** + * Binds keyboard and mouse events to handlers + */ registerKeys: function () { var tabcomplete = {active: false, data: [], prefix: ''}; $('#kiwi_msginput').bind('keydown', function (e) { @@ -242,7 +252,9 @@ kiwi.front.ui = { }, - + /** + * Prompts user for a new nick + */ showChangeNick: function (caption) { caption = (typeof caption !== 'undefined') ? caption : ''; @@ -278,7 +290,9 @@ kiwi.front.ui = { }, - + /** + * Displays the current channel's topic in the topic bar + */ setTopicText: function (new_topic) { kiwi.front.cache.original_topic = new_topic; $('#kiwi .cur_topic .topic').text(new_topic); @@ -287,19 +301,27 @@ kiwi.front.ui = { - + /** + * + */ tabviewsNext: function () { var wl = $('#kiwi .windowlist ul'), next_left = parseInt(wl.css('text-indent').replace('px', ''), 10) + 170; wl.css('text-indent', next_left); }, + /** + * + */ tabviewsPrevious: function () { var wl = $('#kiwi .windowlist ul'), next_left = parseInt(wl.css('text-indent').replace('px', ''), 10) - 170; wl.css('text-indent', next_left); }, + /** + * Displays the next tab + */ windowsNext: function () { var tab, tabs, curTab, next; next = false; @@ -318,6 +340,9 @@ kiwi.front.ui = { } }, + /** + * Displays the previous tab + */ windowsPrevious: function () { var tab, tabs, curTab, prev_tab, next; next = false; @@ -334,6 +359,10 @@ kiwi.front.ui = { } }, + /** + * Shows a specific tab + * @param {Number} num The index of the tab to show + */ windowsShow: function (num) { num = parseInt(num, 10); console.log('Showing window ' + num.toString()); @@ -349,7 +378,9 @@ kiwi.front.ui = { }, - + /** + * + */ barsShow: function () { $('#kiwi .control').slideDown(); $('#kiwi .toolbars').slideDown(400, function () { @@ -357,6 +388,9 @@ kiwi.front.ui = { }); }, + /** + * + */ barsHide: function () { $('#kiwi .control').slideUp(); $('#kiwi .toolbars').slideUp(400, function () { @@ -370,7 +404,9 @@ kiwi.front.ui = { - + /** + * Displays the tutorial + */ tutorial: function () { var b = $('
'), bounds, @@ -380,6 +416,9 @@ kiwi.front.ui = { b.css({display: 'block', position: 'absolute', height:'100%', width:'100%'}); $('#kiwi').append(b); + /** + * @inner + */ bounds = function (el) { var b = 3, ret = {}; ret.top = el.offset().top; @@ -413,6 +452,9 @@ kiwi.front.ui = { current_s = -1; + /** + * @inner + */ next_s = function () { current_s++; if (typeof s[current_s] === 'function') { diff --git a/client/js/gateway.js b/client/js/gateway.js index 6b15932..09e2746 100644 --- a/client/js/gateway.js +++ b/client/js/gateway.js @@ -1,21 +1,67 @@ /*jslint devel: true, browser: true, confusion: true, sloppy: true, maxerr: 50, indent: 4 */ /*globals io, $, kiwi, kiwi_server */ +/** + @namespace Gateway between the client and server +*/ kiwi.gateway = { + /** + * The current nickname + * @type String + */ nick: 'kiwi', + /** + * The session ID + */ session_id: null, + /** + * Whether we're syncing or not + * @type Boolean + */ syncing: false, + /** + * The channel prefix for this network + * @type String + */ channel_prefix: '#', + /** + * The name of the network + * @type String + */ network_name: '', + /** + * The user prefixes for channel owner/admin/op/voice etc. on this network + * @type Array + */ user_prefixes: ['~', '&', '@', '+'], + /** + * The Socket.IO socket + * @type Object + */ socket: null, + /** + * The location of the remote Socket.IO endpoint + * @type String + */ kiwi_server: null, + /** + * Configures {@link kiwi.gateway.kiwi_server} + * @param {String} kiwi_server The location of the remote Socket.IO endpoint + */ start: function (kiwi_server) { if (typeof kiwi_server !== 'undefined') { kiwi.gateway.kiwi_server = kiwi_server; } }, + /** + * Connects to the server + * @param {String} host The hostname or IP address of the IRC server to connect to + * @param {Number} port The port of the IRC server to connect to + * @param {Boolean} ssl Whether or not to connect to the IRC server using SSL + * @param {String} password The password to supply to the IRC server during registration + * @param {Function} callback A callback function to be invoked once Kiwi's server has connected to the IRC server + */ connect: function (host, port, ssl, password, callback) { if (typeof kiwi.gateway.kiwi_server !== 'undefined') { kiwi.gateway.socket = io.connect(kiwi_server, { @@ -95,6 +141,9 @@ kiwi.gateway = { syncchannel_redirect debug */ + /** + * Parses the response from the server + */ parse: function (item) { if (item.event !== undefined) { $(kiwi.gateway).trigger("on" + item.event, item); @@ -130,8 +179,20 @@ kiwi.gateway = { } }, - sendData: function () {}, + /** + * Sends data to the server + * @private + * @param {Object} data The data to send + * @param {Function} callback A callback function + */ + sendData: function (data, callback) {}, + /** + * Sends a PRIVMSG message + * @param {String} target The target of the message (e.g. a channel or nick) + * @param {String} msg The message to send + * @param {Function} callback A callback function + */ privmsg: function (target, msg, callback) { var data = { method: 'privmsg', @@ -144,6 +205,12 @@ kiwi.gateway = { kiwi.gateway.sendData(data, callback); }, + /** + * Sends a NOTICE message + * @param {String} target The target of the message (e.g. a channel or nick) + * @param {String} msg The message to send + * @param {Function} callback A callback function + */ notice: function (target, msg, callback) { var data = { method: 'notice', @@ -156,6 +223,14 @@ kiwi.gateway = { kiwi.gateway.sendData(data, callback); }, + /** + * Sends a CTCP message + * @param {Boolean} request Indicates whether this is a CTCP request (true) or reply (false) + * @param {String} type The type of CTCP message, e.g. 'VERSION', 'TIME', 'PING' etc. + * @param {String} target The target of the message, e.g a channel or nick + * @param {String} params Additional paramaters + * @param {Function} callback A callback function + */ ctcp: function (request, type, target, params, callback) { var data = { method: 'ctcp', @@ -170,10 +245,21 @@ kiwi.gateway = { kiwi.gateway.sendData(data, callback); }, + /** + * @param {String} target The target of the message (e.g. a channel or nick) + * @param {String} msg The message to send + * @param {Function} callback A callback function + */ action: function (target, msg, callback) { this.ctcp(true, 'ACTION', target, msg, callback); }, + /** + * Joins a channel + * @param {String} channel The channel to join + * @param {String} key The key to the channel + * @param {Function} callback A callback function + */ join: function (channel, key, callback) { var data = { method: 'join', @@ -186,6 +272,11 @@ kiwi.gateway = { kiwi.gateway.sendData(data, callback); }, + /** + * Leaves a channel + * @param {String} channel The channel to part + * @param {Function} callback A callback function + */ part: function (channel, callback) { var data = { method: 'part', @@ -197,6 +288,12 @@ kiwi.gateway = { kiwi.gateway.sendData(data, callback); }, + /** + * Queries or modifies a channell topic + * @param {String} channel The channel to query or modify + * @param {String} new_topic The new topic to set + * @param {Function} callback A callback function + */ topic: function (channel, new_topic, callback) { var data = { method: 'topic', @@ -209,6 +306,13 @@ kiwi.gateway = { kiwi.gateway.sendData(data, callback); }, + /** + * Kicks a user from a channel + * @param {String} channel The channel to kick the user from + * @param {String} nick The nick of the user to kick + * @param {String} reason The reason for kicking the user + * @param {Function} callback A callback function + */ kick: function (channel, nick, reason, callback) { var data = { method: 'kick', @@ -222,6 +326,11 @@ kiwi.gateway = { kiwi.gateway.sendData(data, callback); }, + /** + * Disconnects us from the server + * @param {String} msg The quit message to send to the IRC server + * @param {Function} callback A callback function + */ quit: function (msg, callback) { msg = msg || ""; var data = { @@ -234,6 +343,11 @@ kiwi.gateway = { kiwi.gateway.sendData(data, callback); }, + /** + * Sends a string unmodified to the IRC server + * @param {String} data The data to send to the IRC server + * @param {Function} callback A callback function + */ raw: function (data, callback) { var data = { method: 'raw', @@ -245,6 +359,11 @@ kiwi.gateway = { kiwi.gateway.sendData(data, callback); }, + /** + * Changes our nickname + * @param {String} new_nick Our new nickname + * @param {Function} callback A callback function + */ nick: function (new_nick, callback) { var data = { method: 'nick', @@ -255,7 +374,13 @@ kiwi.gateway = { kiwi.gateway.sendData(data, callback); }, - + + /** + * Sends data to a fellow Kiwi IRC user + * @param {String} target The nick of the Kiwi IRC user to send to + * @param {String} data The data to send + * @param {Function} callback A callback function + */ kiwi: function (target, data, callback) { var data = { method: 'kiwi', diff --git a/client/js/util.js b/client/js/util.js index 9749f6c..86f284c 100644 --- a/client/js/util.js +++ b/client/js/util.js @@ -2,11 +2,17 @@ /*globals $, front, gateway, Utilityview */ // Holds anything kiwi client specific (ie. front, gateway, kiwi.plugs..) +/** +* @namespace +*/ var kiwi = {}; - +/** +* Suppresses console.log +* @param {Boolean} debug Whether to re-enable console.log or not +*/ function manageDebug(debug) { var log, consoleBackUp; if (window.console) { @@ -27,7 +33,11 @@ function manageDebug(debug) { } } - +/** +* Generate a random string of given length +* @param {Number} string_length The length of the random string +* @returns {String} The random string +*/ function randomString(string_length) { var chars = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXTZabcdefghiklmnopqrstuvwxyz", randomstring = '', @@ -40,12 +50,21 @@ function randomString(string_length) { return randomstring; } +/** +* String.trim shim +*/ if (typeof String.prototype.trim === 'undefined') { String.prototype.trim = function () { return this.replace(/^\s+|\s+$/g, ""); }; } +/** +* String.lpad shim +* @param {Number} length The length of padding +* @param {String} characher The character to pad with +* @returns {String} The padded string +*/ if (typeof String.prototype.lpad === 'undefined') { String.prototype.lpad = function (length, character) { var padding = "", @@ -58,7 +77,11 @@ if (typeof String.prototype.lpad === 'undefined') { } - +/** +* Convert seconds into hours:minutes:seconds +* @param {Number} secs The number of seconds to converts +* @returns {Object} An object representing the hours/minutes/second conversion of secs +*/ function secondsToTime(secs) { var hours, minutes, seconds, divisor_for_minutes, divisor_for_seconds, obj; hours = Math.floor(secs / (60 * 60)); @@ -199,7 +222,7 @@ var plugins = [ }, - /** + /* * Disabled due to many websites closing kiwi with iframe busting { name: "inBrowser", @@ -316,9 +339,19 @@ var plugins = [ - +/** +* @namespace +*/ kiwi.plugs = {}; +/** +* Loaded plugins +*/ kiwi.plugs.loaded = {}; +/** +* Load a plugin +* @param {Object} plugin The plugin to be loaded +* @returns {Boolean} True on success, false on failure +*/ kiwi.plugs.loadPlugin = function (plugin) { var plugin_ret; if (typeof plugin.name !== 'string') { @@ -335,6 +368,10 @@ kiwi.plugs.loadPlugin = function (plugin) { return true; }; +/** +* Unload a plugin +* @param {String} plugin_name The name of the plugin to unload +*/ kiwi.plugs.unloadPlugin = function (plugin_name) { if (typeof kiwi.plugs.loaded[plugin_name] !== 'object') { return; @@ -346,9 +383,13 @@ kiwi.plugs.unloadPlugin = function (plugin_name) { -/* - * Run an event against all loaded plugins - */ +/** +* Run an event against all loaded plugins +* @param {String} event_name The name of the event +* @param {Object} event_data The data to pass to the plugin +* @param {Object} opts Options +* @returns {Object} Event data, possibly modified by the plugins +*/ kiwi.plugs.run = function (event_name, event_data, opts) { var ret = event_data, ret_tmp, @@ -386,7 +427,10 @@ kiwi.plugs.run = function (event_name, event_data, opts) { - +/** +* @constructor +* @param {String} data_namespace The namespace for the data store +*/ kiwi.dataStore = function (data_namespace) { var namespace = data_namespace; -- 2.25.1