From db1f37a411199b7ae6fa9fa5aae5dca2fff35585 Mon Sep 17 00:00:00 2001
From: Damyon Wiese <damyon@moodle.com>
Date: Fri, 20 Sep 2013 14:50:17 +0800
Subject: [PATCH] MDL-41241 atto: YUIDoc cleanup for link plugin.

---
 .../moodle-atto_link-button-debug.js          | 121 ++++++++++++++----
 .../moodle-atto_link-button-min.js            |   2 +-
 .../moodle-atto_link-button.js                | 121 ++++++++++++++----
 .../plugins/link/yui/src/button/js/button.js  | 121 ++++++++++++++----
 4 files changed, 280 insertions(+), 85 deletions(-)

diff --git a/lib/editor/atto/plugins/link/yui/build/moodle-atto_link-button/moodle-atto_link-button-debug.js b/lib/editor/atto/plugins/link/yui/build/moodle-atto_link-button/moodle-atto_link-button-debug.js
index c352f07b7fe..b41a1b154ca 100644
--- a/lib/editor/atto/plugins/link/yui/build/moodle-atto_link-button/moodle-atto_link-button-debug.js
+++ b/lib/editor/atto/plugins/link/yui/build/moodle-atto_link-button/moodle-atto_link-button-debug.js
@@ -23,41 +23,77 @@ YUI.add('moodle-atto_link-button', function (Y, NAME) {
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 M.atto_link = M.atto_link || {
+    /**
+     * The window used to get the link details.
+     *
+     * @property dialogue
+     * @type M.core.dialogue
+     * @default null
+     */
     dialogue : null,
+
+    /**
+     * The selection object returned by the browser.
+     *
+     * @property selection
+     * @type Range
+     * @default null
+     */
     selection : null,
-    init : function(params) {
-        var display_chooser = function(e, elementid) {
-            e.preventDefault();
-            if (!M.editor_atto.is_active(elementid)) {
-                M.editor_atto.focus(elementid);
+
+    /**
+     * Display the chooser dialogue.
+     *
+     * @method init
+     * @param Event e
+     * @param string elementid
+     */
+    display_chooser : function(e, elementid) {
+        e.preventDefault();
+        if (!M.editor_atto.is_active(elementid)) {
+            M.editor_atto.focus(elementid);
+        }
+        M.atto_link.selection = M.editor_atto.get_selection();
+        if (M.atto_link.selection !== false && (!M.atto_link.selection.collapsed)) {
+            var dialogue;
+            if (!M.atto_link.dialogue) {
+                dialogue = new M.core.dialogue({
+                    visible: false,
+                    modal: true,
+                    close: true,
+                    draggable: true
+                });
+            } else {
+                dialogue = M.atto_link.dialogue;
             }
-            M.atto_link.selection = M.editor_atto.get_selection();
-            if (M.atto_link.selection !== false && (!M.atto_link.selection.collapsed)) {
-                var dialogue;
-                if (!M.atto_link.dialogue) {
-                    dialogue = new M.core.dialogue({
-                        visible: false,
-                        modal: true,
-                        close: true,
-                        draggable: true
-                    });
-                } else {
-                    dialogue = M.atto_link.dialogue;
-                }
 
-                dialogue.render();
-                dialogue.set('bodyContent', M.atto_link.get_form_content(elementid));
-                dialogue.set('headerContent', M.util.get_string('createlink', 'atto_link'));
+            dialogue.render();
+            dialogue.set('bodyContent', M.atto_link.get_form_content(elementid));
+            dialogue.set('headerContent', M.util.get_string('createlink', 'atto_link'));
 
-                M.atto_link.resolve_anchors();
+            M.atto_link.resolve_anchors();
 
-                dialogue.show();
-                M.atto_link.dialogue = dialogue;
-            }
-        };
-
-        M.editor_atto.add_toolbar_button(params.elementid, 'link', params.icon, display_chooser, this);
+            dialogue.show();
+            M.atto_link.dialogue = dialogue;
+        }
     },
+
+    /**
+     * Add this button to the form.
+     *
+     * @method init
+     * @param {Object} params
+     */
+    init : function(params) {
+        M.editor_atto.add_toolbar_button(params.elementid, 'link', params.icon, this.display_chooser, this);
+    },
+
+    /**
+     * If there is selected text and it is part of an anchor link,
+     * extract the url (and target) from the link (and set them in the form).
+     *
+     * @method resolve_anchors
+     */
     resolve_anchors : function() {
         // Find the first anchor tag in the selection.
         var selectednode = M.editor_atto.get_selection_parent_node(),
@@ -79,12 +115,26 @@ M.atto_link = M.atto_link || {
             }
         }
     },
+
+    /**
+     * Open the repository file picker.
+     *
+     * @method open_filepicker
+     * @param Event e
+     */
     open_filepicker : function(e) {
         var elementid = this.getAttribute('data-editor');
         e.preventDefault();
 
         M.editor_atto.show_filepicker(elementid, 'link', M.atto_link.filepicker_callback);
     },
+
+    /**
+     * Called by the file picker when a link has been chosen.
+     *
+     * @method filepicker_callback
+     * @param {Object} params - contains selected url.
+     */
     filepicker_callback : function(params) {
         M.atto_link.dialogue.hide();
         if (params.url !== '') {
@@ -93,6 +143,13 @@ M.atto_link = M.atto_link || {
             document.execCommand('createLink', false, params.url);
         }
     },
+
+    /**
+     * The OK button has been pressed - make the changes to the source.
+     *
+     * @method set_link
+     * @param Event e
+     */
     set_link : function(e) {
         e.preventDefault();
         M.atto_link.dialogue.hide();
@@ -106,6 +163,14 @@ M.atto_link = M.atto_link || {
             document.execCommand('createLink', false, value);
         }
     },
+
+    /**
+     * Return the HTML of the form to show in the dialogue.
+     *
+     * @method get_form_content
+     * @param string elementid
+     * @return string
+     */
     get_form_content : function(elementid) {
         var content = Y.Node.create('<form>' +
                              '<label for="atto_link_urlentry">' + M.util.get_string('enterurl', 'atto_link') +
diff --git a/lib/editor/atto/plugins/link/yui/build/moodle-atto_link-button/moodle-atto_link-button-min.js b/lib/editor/atto/plugins/link/yui/build/moodle-atto_link-button/moodle-atto_link-button-min.js
index 64546785d78..06b6b58332a 100644
--- a/lib/editor/atto/plugins/link/yui/build/moodle-atto_link-button/moodle-atto_link-button-min.js
+++ b/lib/editor/atto/plugins/link/yui/build/moodle-atto_link-button/moodle-atto_link-button-min.js
@@ -1 +1 @@
-YUI.add("moodle-atto_link-button",function(e,t){M.atto_link=M.atto_link||{dialogue:null,selection:null,init:function(e){var t=function(e,t){e.preventDefault(),M.editor_atto.is_active(t)||M.editor_atto.focus(t),M.atto_link.selection=M.editor_atto.get_selection();if(M.atto_link.selection!==!1&&!M.atto_link.selection.collapsed){var n;M.atto_link.dialogue?n=M.atto_link.dialogue:n=new M.core.dialogue({visible:!1,modal:!0,close:!0,draggable:!0}),n.render(),n.set("bodyContent",M.atto_link.get_form_content(t)),n.set("headerContent",M.util.get_string("createlink","atto_link")),M.atto_link.resolve_anchors(),n.show(),M.atto_link.dialogue=n}};M.editor_atto.add_toolbar_button(e.elementid,"link",e.icon,t,this)},resolve_anchors:function(){var t=M.editor_atto.get_selection_parent_node(),n,r;if(!t)return;n=e.one(t).ancestor("a"),n&&(r=n.getAttribute("href"),r!==""&&(M.atto_link.selection=M.editor_atto.get_selection_from_node(n),e.one("#atto_link_urlentry").set("value",r)))},open_filepicker:function(e){var t=this.getAttribute("data-editor");e.preventDefault(),M.editor_atto.show_filepicker(t,"link",M.atto_link.filepicker_callback)},filepicker_callback:function(e){M.atto_link.dialogue.hide(),e.url!==""&&(M.editor_atto.set_selection(M.atto_link.selection),document.execCommand("unlink",!1,null),document.execCommand("createLink",!1,e.url))},set_link:function(e){e.preventDefault(),M.atto_link.dialogue.hide();var t=e.currentTarget.get("parentNode").one("input"),n=t.get("value");n!==""&&(M.editor_atto.set_selection(M.atto_link.selection),document.execCommand("unlink",!1,null),document.execCommand("createLink",!1,n))},get_form_content:function(t){var n=e.Node.create('<form><label for="atto_link_urlentry">'+M.util.get_string("enterurl","atto_link")+"</label><br/>"+'<input type="url" value="" id="atto_link_urlentry" size="32"/>'+"<br/>"+'<button id="openlinkbrowser" data-editor="'+e.Escape.html(t)+'">'+M.util.get_string("browserepositories","atto_link")+"</button>"+"<hr/>"+'<button id="atto_link_urlentrysubmit">'+M.util.get_string("createlink","atto_link")+"</button>"+"</form>"+"<hr/>"+M.util.get_string("accessibilityhint","atto_link"));return n.one("#atto_link_urlentrysubmit").on("click",M.atto_link.set_link),n.one("#openlinkbrowser").on("click",M.atto_link.open_filepicker),n}}},"@VERSION@",{requires:["node","escape"]});
+YUI.add("moodle-atto_link-button",function(e,t){M.atto_link=M.atto_link||{dialogue:null,selection:null,display_chooser:function(e,t){e.preventDefault(),M.editor_atto.is_active(t)||M.editor_atto.focus(t),M.atto_link.selection=M.editor_atto.get_selection();if(M.atto_link.selection!==!1&&!M.atto_link.selection.collapsed){var n;M.atto_link.dialogue?n=M.atto_link.dialogue:n=new M.core.dialogue({visible:!1,modal:!0,close:!0,draggable:!0}),n.render(),n.set("bodyContent",M.atto_link.get_form_content(t)),n.set("headerContent",M.util.get_string("createlink","atto_link")),M.atto_link.resolve_anchors(),n.show(),M.atto_link.dialogue=n}},init:function(e){M.editor_atto.add_toolbar_button(e.elementid,"link",e.icon,this.display_chooser,this)},resolve_anchors:function(){var t=M.editor_atto.get_selection_parent_node(),n,r;if(!t)return;n=e.one(t).ancestor("a"),n&&(r=n.getAttribute("href"),r!==""&&(M.atto_link.selection=M.editor_atto.get_selection_from_node(n),e.one("#atto_link_urlentry").set("value",r)))},open_filepicker:function(e){var t=this.getAttribute("data-editor");e.preventDefault(),M.editor_atto.show_filepicker(t,"link",M.atto_link.filepicker_callback)},filepicker_callback:function(e){M.atto_link.dialogue.hide(),e.url!==""&&(M.editor_atto.set_selection(M.atto_link.selection),document.execCommand("unlink",!1,null),document.execCommand("createLink",!1,e.url))},set_link:function(e){e.preventDefault(),M.atto_link.dialogue.hide();var t=e.currentTarget.get("parentNode").one("input"),n=t.get("value");n!==""&&(M.editor_atto.set_selection(M.atto_link.selection),document.execCommand("unlink",!1,null),document.execCommand("createLink",!1,n))},get_form_content:function(t){var n=e.Node.create('<form><label for="atto_link_urlentry">'+M.util.get_string("enterurl","atto_link")+"</label><br/>"+'<input type="url" value="" id="atto_link_urlentry" size="32"/>'+"<br/>"+'<button id="openlinkbrowser" data-editor="'+e.Escape.html(t)+'">'+M.util.get_string("browserepositories","atto_link")+"</button>"+"<hr/>"+'<button id="atto_link_urlentrysubmit">'+M.util.get_string("createlink","atto_link")+"</button>"+"</form>"+"<hr/>"+M.util.get_string("accessibilityhint","atto_link"));return n.one("#atto_link_urlentrysubmit").on("click",M.atto_link.set_link),n.one("#openlinkbrowser").on("click",M.atto_link.open_filepicker),n}}},"@VERSION@",{requires:["node","escape"]});
diff --git a/lib/editor/atto/plugins/link/yui/build/moodle-atto_link-button/moodle-atto_link-button.js b/lib/editor/atto/plugins/link/yui/build/moodle-atto_link-button/moodle-atto_link-button.js
index c352f07b7fe..b41a1b154ca 100644
--- a/lib/editor/atto/plugins/link/yui/build/moodle-atto_link-button/moodle-atto_link-button.js
+++ b/lib/editor/atto/plugins/link/yui/build/moodle-atto_link-button/moodle-atto_link-button.js
@@ -23,41 +23,77 @@ YUI.add('moodle-atto_link-button', function (Y, NAME) {
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 M.atto_link = M.atto_link || {
+    /**
+     * The window used to get the link details.
+     *
+     * @property dialogue
+     * @type M.core.dialogue
+     * @default null
+     */
     dialogue : null,
+
+    /**
+     * The selection object returned by the browser.
+     *
+     * @property selection
+     * @type Range
+     * @default null
+     */
     selection : null,
-    init : function(params) {
-        var display_chooser = function(e, elementid) {
-            e.preventDefault();
-            if (!M.editor_atto.is_active(elementid)) {
-                M.editor_atto.focus(elementid);
+
+    /**
+     * Display the chooser dialogue.
+     *
+     * @method init
+     * @param Event e
+     * @param string elementid
+     */
+    display_chooser : function(e, elementid) {
+        e.preventDefault();
+        if (!M.editor_atto.is_active(elementid)) {
+            M.editor_atto.focus(elementid);
+        }
+        M.atto_link.selection = M.editor_atto.get_selection();
+        if (M.atto_link.selection !== false && (!M.atto_link.selection.collapsed)) {
+            var dialogue;
+            if (!M.atto_link.dialogue) {
+                dialogue = new M.core.dialogue({
+                    visible: false,
+                    modal: true,
+                    close: true,
+                    draggable: true
+                });
+            } else {
+                dialogue = M.atto_link.dialogue;
             }
-            M.atto_link.selection = M.editor_atto.get_selection();
-            if (M.atto_link.selection !== false && (!M.atto_link.selection.collapsed)) {
-                var dialogue;
-                if (!M.atto_link.dialogue) {
-                    dialogue = new M.core.dialogue({
-                        visible: false,
-                        modal: true,
-                        close: true,
-                        draggable: true
-                    });
-                } else {
-                    dialogue = M.atto_link.dialogue;
-                }
 
-                dialogue.render();
-                dialogue.set('bodyContent', M.atto_link.get_form_content(elementid));
-                dialogue.set('headerContent', M.util.get_string('createlink', 'atto_link'));
+            dialogue.render();
+            dialogue.set('bodyContent', M.atto_link.get_form_content(elementid));
+            dialogue.set('headerContent', M.util.get_string('createlink', 'atto_link'));
 
-                M.atto_link.resolve_anchors();
+            M.atto_link.resolve_anchors();
 
-                dialogue.show();
-                M.atto_link.dialogue = dialogue;
-            }
-        };
-
-        M.editor_atto.add_toolbar_button(params.elementid, 'link', params.icon, display_chooser, this);
+            dialogue.show();
+            M.atto_link.dialogue = dialogue;
+        }
     },
+
+    /**
+     * Add this button to the form.
+     *
+     * @method init
+     * @param {Object} params
+     */
+    init : function(params) {
+        M.editor_atto.add_toolbar_button(params.elementid, 'link', params.icon, this.display_chooser, this);
+    },
+
+    /**
+     * If there is selected text and it is part of an anchor link,
+     * extract the url (and target) from the link (and set them in the form).
+     *
+     * @method resolve_anchors
+     */
     resolve_anchors : function() {
         // Find the first anchor tag in the selection.
         var selectednode = M.editor_atto.get_selection_parent_node(),
@@ -79,12 +115,26 @@ M.atto_link = M.atto_link || {
             }
         }
     },
+
+    /**
+     * Open the repository file picker.
+     *
+     * @method open_filepicker
+     * @param Event e
+     */
     open_filepicker : function(e) {
         var elementid = this.getAttribute('data-editor');
         e.preventDefault();
 
         M.editor_atto.show_filepicker(elementid, 'link', M.atto_link.filepicker_callback);
     },
+
+    /**
+     * Called by the file picker when a link has been chosen.
+     *
+     * @method filepicker_callback
+     * @param {Object} params - contains selected url.
+     */
     filepicker_callback : function(params) {
         M.atto_link.dialogue.hide();
         if (params.url !== '') {
@@ -93,6 +143,13 @@ M.atto_link = M.atto_link || {
             document.execCommand('createLink', false, params.url);
         }
     },
+
+    /**
+     * The OK button has been pressed - make the changes to the source.
+     *
+     * @method set_link
+     * @param Event e
+     */
     set_link : function(e) {
         e.preventDefault();
         M.atto_link.dialogue.hide();
@@ -106,6 +163,14 @@ M.atto_link = M.atto_link || {
             document.execCommand('createLink', false, value);
         }
     },
+
+    /**
+     * Return the HTML of the form to show in the dialogue.
+     *
+     * @method get_form_content
+     * @param string elementid
+     * @return string
+     */
     get_form_content : function(elementid) {
         var content = Y.Node.create('<form>' +
                              '<label for="atto_link_urlentry">' + M.util.get_string('enterurl', 'atto_link') +
diff --git a/lib/editor/atto/plugins/link/yui/src/button/js/button.js b/lib/editor/atto/plugins/link/yui/src/button/js/button.js
index b719e9a92b5..9ed2eba9a18 100644
--- a/lib/editor/atto/plugins/link/yui/src/button/js/button.js
+++ b/lib/editor/atto/plugins/link/yui/src/button/js/button.js
@@ -21,41 +21,77 @@
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 M.atto_link = M.atto_link || {
+    /**
+     * The window used to get the link details.
+     *
+     * @property dialogue
+     * @type M.core.dialogue
+     * @default null
+     */
     dialogue : null,
+
+    /**
+     * The selection object returned by the browser.
+     *
+     * @property selection
+     * @type Range
+     * @default null
+     */
     selection : null,
-    init : function(params) {
-        var display_chooser = function(e, elementid) {
-            e.preventDefault();
-            if (!M.editor_atto.is_active(elementid)) {
-                M.editor_atto.focus(elementid);
+
+    /**
+     * Display the chooser dialogue.
+     *
+     * @method init
+     * @param Event e
+     * @param string elementid
+     */
+    display_chooser : function(e, elementid) {
+        e.preventDefault();
+        if (!M.editor_atto.is_active(elementid)) {
+            M.editor_atto.focus(elementid);
+        }
+        M.atto_link.selection = M.editor_atto.get_selection();
+        if (M.atto_link.selection !== false && (!M.atto_link.selection.collapsed)) {
+            var dialogue;
+            if (!M.atto_link.dialogue) {
+                dialogue = new M.core.dialogue({
+                    visible: false,
+                    modal: true,
+                    close: true,
+                    draggable: true
+                });
+            } else {
+                dialogue = M.atto_link.dialogue;
             }
-            M.atto_link.selection = M.editor_atto.get_selection();
-            if (M.atto_link.selection !== false && (!M.atto_link.selection.collapsed)) {
-                var dialogue;
-                if (!M.atto_link.dialogue) {
-                    dialogue = new M.core.dialogue({
-                        visible: false,
-                        modal: true,
-                        close: true,
-                        draggable: true
-                    });
-                } else {
-                    dialogue = M.atto_link.dialogue;
-                }
 
-                dialogue.render();
-                dialogue.set('bodyContent', M.atto_link.get_form_content(elementid));
-                dialogue.set('headerContent', M.util.get_string('createlink', 'atto_link'));
+            dialogue.render();
+            dialogue.set('bodyContent', M.atto_link.get_form_content(elementid));
+            dialogue.set('headerContent', M.util.get_string('createlink', 'atto_link'));
 
-                M.atto_link.resolve_anchors();
+            M.atto_link.resolve_anchors();
 
-                dialogue.show();
-                M.atto_link.dialogue = dialogue;
-            }
-        };
-
-        M.editor_atto.add_toolbar_button(params.elementid, 'link', params.icon, display_chooser, this);
+            dialogue.show();
+            M.atto_link.dialogue = dialogue;
+        }
     },
+
+    /**
+     * Add this button to the form.
+     *
+     * @method init
+     * @param {Object} params
+     */
+    init : function(params) {
+        M.editor_atto.add_toolbar_button(params.elementid, 'link', params.icon, this.display_chooser, this);
+    },
+
+    /**
+     * If there is selected text and it is part of an anchor link,
+     * extract the url (and target) from the link (and set them in the form).
+     *
+     * @method resolve_anchors
+     */
     resolve_anchors : function() {
         // Find the first anchor tag in the selection.
         var selectednode = M.editor_atto.get_selection_parent_node(),
@@ -77,12 +113,26 @@ M.atto_link = M.atto_link || {
             }
         }
     },
+
+    /**
+     * Open the repository file picker.
+     *
+     * @method open_filepicker
+     * @param Event e
+     */
     open_filepicker : function(e) {
         var elementid = this.getAttribute('data-editor');
         e.preventDefault();
 
         M.editor_atto.show_filepicker(elementid, 'link', M.atto_link.filepicker_callback);
     },
+
+    /**
+     * Called by the file picker when a link has been chosen.
+     *
+     * @method filepicker_callback
+     * @param {Object} params - contains selected url.
+     */
     filepicker_callback : function(params) {
         M.atto_link.dialogue.hide();
         if (params.url !== '') {
@@ -91,6 +141,13 @@ M.atto_link = M.atto_link || {
             document.execCommand('createLink', false, params.url);
         }
     },
+
+    /**
+     * The OK button has been pressed - make the changes to the source.
+     *
+     * @method set_link
+     * @param Event e
+     */
     set_link : function(e) {
         e.preventDefault();
         M.atto_link.dialogue.hide();
@@ -104,6 +161,14 @@ M.atto_link = M.atto_link || {
             document.execCommand('createLink', false, value);
         }
     },
+
+    /**
+     * Return the HTML of the form to show in the dialogue.
+     *
+     * @method get_form_content
+     * @param string elementid
+     * @return string
+     */
     get_form_content : function(elementid) {
         var content = Y.Node.create('<form>' +
                              '<label for="atto_link_urlentry">' + M.util.get_string('enterurl', 'atto_link') +