From f901c25012f6c83f70c83bff9e76edb4d01b8373 Mon Sep 17 00:00:00 2001 From: Brion Vibber Date: Thu, 16 Dec 2010 15:34:51 -0800 Subject: [PATCH 1/1] Add lots of doc comments to util.js. Most stuff makes some kind of stuff, but some is kinda.... funky :D These comments are all stripped during minification, so util.min.js remains unchanged. --- js/util.js | 118 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) diff --git a/js/util.js b/js/util.js index 74d6500c13..99f15e7171 100644 --- a/js/util.js +++ b/js/util.js @@ -622,6 +622,9 @@ var SN = { // StatusNet /** * Setup function -- DOES NOT trigger actions immediately. + * + * Goes through all notices currently displayed and sets up attachment + * handling if needed. */ NoticeAttachments: function() { $('.notice a.attachment').each(function() { @@ -629,6 +632,16 @@ var SN = { // StatusNet }); }, + /** + * Setup function -- DOES NOT trigger actions immediately. + * + * Sets up special attachment link handling if needed. Currently this + * consists only of making the "more" button used for OStatus message + * cropping turn into an auto-expansion button that loads the full + * text from an attachment file. + * + * @param {jQuery} notice + */ NoticeWithAttachment: function(notice) { if (notice.find('.attachment').length === 0) { return; @@ -648,6 +661,17 @@ var SN = { // StatusNet } }, + /** + * Setup function -- DOES NOT trigger actions immediately. + * + * Sets up event handlers for the file-attachment widget in the + * new notice form. When a file is selected, a box will be added + * below the text input showing the filename and, if supported + * by the browser, a thumbnail preview. + * + * This preview box will also allow removing the attachment + * prior to posting. + */ NoticeDataAttach: function() { NDA = $('#'+SN.C.S.NoticeDataAttach); NDA.change(function() { @@ -762,6 +786,18 @@ var SN = { // StatusNet } }, + /** + * Setup function -- DOES NOT trigger actions immediately. + * + * Initializes state for the location-lookup features in the + * new-notice form. Seems to set up some event handlers for + * triggering lookups and using the new values. + * + * @fixme tl;dr + * @fixme there's not good visual state update here, so users have a + * hard time figuring out if it's working or fixing if it's wrong. + * + */ NoticeLocationAttach: function() { var NLat = $('#'+SN.C.S.NoticeLat).val(); var NLon = $('#'+SN.C.S.NoticeLon).val(); @@ -919,6 +955,18 @@ var SN = { // StatusNet } }, + /** + * Setup function -- DOES NOT trigger actions immediately. + * + * Initializes event handlers for the "Send direct message" link on + * profile pages, setting it up to display a dialog box when clicked. + * + * Unlike the repeat confirmation form, this appears to fetch + * the form _from the original link target_, so the form itself + * doesn't need to be in the current document. + * + * @fixme breaks ability to open link in new window? + */ NewDirectMessage: function() { NDM = $('.entity_send-a-message a'); NDM.attr({'href':NDM.attr('href')+'&ajax=1'}); @@ -947,6 +995,15 @@ var SN = { // StatusNet }); }, + /** + * Return a date object with the current local time on the + * given year, month, and day. + * + * @param {number} year: 4-digit year + * @param {number} month: 0 == January + * @param {number} day: 1 == 1 + * @return {Date} + */ GetFullYear: function(year, month, day) { var date = new Date(); date.setFullYear(year, month, day); @@ -954,7 +1011,22 @@ var SN = { // StatusNet return date; }, + /** + * Some sort of object interface for storing some structured + * information in a cookie. + * + * Appears to be used to save the last-used login nickname? + * That's something that browsers usually take care of for us + * these days, do we really need to do it? Does anything else + * use this interface? + * + * @fixme what is this? + * @fixme should this use non-cookie local storage when available? + */ StatusNetInstance: { + /** + * @fixme what is this? + */ Set: function(value) { var SNI = SN.U.StatusNetInstance.Get(); if (SNI !== null) { @@ -970,6 +1042,9 @@ var SN = { // StatusNet }); }, + /** + * @fixme what is this? + */ Get: function() { var cookieValue = $.cookie(SN.C.S.StatusNetInstance); if (cookieValue !== null) { @@ -978,6 +1053,9 @@ var SN = { // StatusNet return null; }, + /** + * @fixme what is this? + */ Delete: function() { $.cookie(SN.C.S.StatusNetInstance, null); } @@ -989,6 +1067,9 @@ var SN = { // StatusNet * * @fixme this should be done in a saner way, with machine-readable * info about what page we're looking at. + * + * @param {DOMElement} notice: HTML chunk with formatted notice + * @return boolean */ belongsOnTimeline: function(notice) { var action = $("body").attr('id'); @@ -1017,6 +1098,14 @@ var SN = { // StatusNet }, Init: { + /** + * If user is logged in, run setup code for the new notice form: + * + * - char counter + * - AJAX submission + * - location events + * - file upload events + */ NoticeForm: function() { if ($('body.user_in').length > 0) { SN.U.NoticeLocationAttach(); @@ -1030,6 +1119,12 @@ var SN = { // StatusNet } }, + /** + * Run setup code for notice timeline views items: + * + * - AJAX submission for fave/repeat/reply (if logged in) + * - Attachment link extras ('more' links) + */ Notices: function() { if ($('body.user_in').length > 0) { SN.U.NoticeFavor(); @@ -1040,6 +1135,12 @@ var SN = { // StatusNet SN.U.NoticeAttachments(); }, + /** + * Run setup code for user & group profile page header area if logged in: + * + * - AJAX submission for sub/unsub/join/leave/nudge + * - AJAX form popup for direct-message + */ EntityActions: function() { if ($('body.user_in').length > 0) { $('.form_user_subscribe').live('click', function() { SN.U.FormXHR($(this)); return false; }); @@ -1052,6 +1153,14 @@ var SN = { // StatusNet } }, + /** + * Run setup code for login form: + * + * - loads saved last-used-nickname from cookie + * - sets event handler to save nickname to cookie on submit + * + * @fixme is this necessary? Browsers do their own form saving these days. + */ Login: function() { if (SN.U.StatusNetInstance.Get() !== null) { var nickname = SN.U.StatusNetInstance.Get().Nickname; @@ -1068,6 +1177,13 @@ var SN = { // StatusNet } }; +/** + * Run initialization functions on DOM-ready. + * + * Note that if we're waiting on other scripts to load, this won't happen + * until that's done. To load scripts asynchronously without delaying setup, + * don't start them loading until after DOM-ready time! + */ $(document).ready(function(){ if ($('.'+SN.C.S.FormNotice).length > 0) { SN.Init.NoticeForm(); @@ -1084,6 +1200,7 @@ $(document).ready(function(){ }); // Formerly in xbImportNode.js +// @fixme put it back there -- since we're minifying we can concat in the makefile now /* is this stuff defined? */ if (!document.ELEMENT_NODE) { @@ -1132,6 +1249,7 @@ document._importNode = function(node, allChildren) { } }; +// @fixme put this next bit back too -- since we're minifying we can concat in the makefile now // A shim to implement the W3C Geolocation API Specification using Gears or the Ajax API if (typeof navigator.geolocation == "undefined" || navigator.geolocation.shim ) { (function(){ -- 2.39.5