From 2babe6c672031de7783ac028790b479ecf0d84a3 Mon Sep 17 00:00:00 2001 From: Mark Holmquist Date: Wed, 5 Feb 2014 14:51:35 -0800 Subject: [PATCH] mediawiki.feedback: Add jsduck documentation Change-Id: Idec212381a904f174de7ae63ef57f26c92db6449 --- maintenance/jsduck/categories.json | 6 ++ maintenance/jsduck/config.json | 1 + resources/mediawiki/mediawiki.feedback.js | 104 ++++++++++++++-------- 3 files changed, 75 insertions(+), 36 deletions(-) diff --git a/maintenance/jsduck/categories.json b/maintenance/jsduck/categories.json index b74b032ab3..f1cd2f86f6 100644 --- a/maintenance/jsduck/categories.json +++ b/maintenance/jsduck/categories.json @@ -51,6 +51,12 @@ "classes": [ "mw.page*" ] + }, + { + "name": "Interfaces", + "classes": [ + "mw.Feedback" + ] } ] }, diff --git a/maintenance/jsduck/config.json b/maintenance/jsduck/config.json index e50a054bae..ff1959d29f 100644 --- a/maintenance/jsduck/config.json +++ b/maintenance/jsduck/config.json @@ -11,6 +11,7 @@ "./external.js", "../../resources/mediawiki/mediawiki.js", "../../resources/mediawiki/mediawiki.htmlform.js", + "../../resources/mediawiki/mediawiki.feedback.js", "../../resources/mediawiki/mediawiki.log.js", "../../resources/mediawiki/mediawiki.util.js", "../../resources/mediawiki/mediawiki.Title.js", diff --git a/resources/mediawiki/mediawiki.feedback.js b/resources/mediawiki/mediawiki.feedback.js index 9de69b29ed..a4984846cc 100644 --- a/resources/mediawiki/mediawiki.feedback.js +++ b/resources/mediawiki/mediawiki.feedback.js @@ -1,41 +1,44 @@ -/** +/*! * mediawiki.feedback * * @author Ryan Kaldari, 2010 * @author Neil Kandalgaonkar, 2010-11 * @since 1.19 - * - * This is a way of getting simple feedback from users. It's useful - * for testing new features -- users can give you feedback without - * the difficulty of opening a whole new talk page. For this reason, - * it also tends to collect a wider range of both positive and negative - * comments. However you do need to tend to the feedback page. It will - * get long relatively quickly, and you often get multiple messages - * reporting the same issue. - * - * It takes the form of thing on your page which, when clicked, opens a small - * dialog box. Submitting that dialog box appends its contents to a - * wiki page that you specify, as a new section. - * - * Not compatible with LiquidThreads. - * - * Minimal example in how to use it: - * - * var feedback = new mw.Feedback(); - * $( '#myButton' ).click( function () { feedback.launch(); } ); - * - * You can also launch the feedback form with a prefilled subject and body. - * See the docs for the launch() method. */ ( function ( mw, $ ) { /** - * Thingy for collecting user feedback on a wiki page - * @param {Array} options -- optional, all properties optional. - * api: {mw.Api} if omitted, will just create a standard API - * title: {mw.Title} the title of the page where you collect feedback. Defaults to "Feedback". - * dialogTitleMessageKey: {String} message key for the title of the dialog box - * bugsLink: {mw.Uri|String} url where bugs can be posted - * bugsListLink: {mw.Uri|String} url where bugs can be listed + * This is a way of getting simple feedback from users. It's useful + * for testing new features -- users can give you feedback without + * the difficulty of opening a whole new talk page. For this reason, + * it also tends to collect a wider range of both positive and negative + * comments. However you do need to tend to the feedback page. It will + * get long relatively quickly, and you often get multiple messages + * reporting the same issue. + * + * It takes the form of thing on your page which, when clicked, opens a small + * dialog box. Submitting that dialog box appends its contents to a + * wiki page that you specify, as a new section. + * + * Not compatible with LiquidThreads. + * + * Minimal example in how to use it: + * + * var feedback = new mw.Feedback(); + * $( '#myButton' ).click( function () { feedback.launch(); } ); + * + * You can also launch the feedback form with a prefilled subject and body. + * See the docs for the #launch() method. + * + * @param {Object} [options] + * @param {mw.Api} [options.api] if omitted, will just create a standard API + * @param {mw.Title} [options.title="Feedback"] The title of the page where you collect + * feedback. + * @param {string} [options.dialogTitleMessageKey="feedback-submit"] Message key for the + * title of the dialog box + * @param {string} [options.bugsLink="//bugzilla.wikimedia.org/enter_bug.cgi"] URL where + * bugs can be posted + * @param {mw.Uri|string} [options.bugsListLink="//bugzilla.wikimedia.org/query.cgi"] + * URL where bugs can be listed */ mw.Feedback = function ( options ) { if ( options === undefined ) { @@ -67,6 +70,9 @@ }; mw.Feedback.prototype = { + /** + * Sets up interface + */ setup: function () { var $feedbackPageLink, $bugNoteLink, @@ -148,16 +154,28 @@ }, + /** + * Displays a section of the dialog. + * + * @param {"form"|"bugs"|"submitting"|"thanks"|"error"} s + * The section of the dialog to show. + */ display: function ( s ) { this.$dialog.dialog( { buttons:{} } ); // hide the buttons this.$dialog.find( '.feedback-mode' ).hide(); // hide everything this.$dialog.find( '.feedback-' + s ).show(); // show the desired div }, + /** + * Display the submitting section. + */ displaySubmitting: function () { this.display( 'submitting' ); }, + /** + * Display the bugs section. + */ displayBugs: function () { var fb = this, bugsButtons = {}; @@ -173,6 +191,9 @@ } ); }, + /** + * Display the thanks section. + */ displayThanks: function () { var fb = this, closeButton = {}; @@ -187,9 +208,9 @@ /** * Display the feedback form - * @param {Object} optional prefilled contents for the feedback form. Object with properties: - * subject: {String} - * message: {String} + * @param {Object} [contents] Prefilled contents for the feedback form. + * @param {string} [contents.subject] The subject of the feedback + * @param {string} [contents.message] The content of the feedback */ displayForm: function ( contents ) { var fb = this, @@ -209,6 +230,11 @@ this.$dialog.dialog( { buttons: formButtons } ); // put the buttons back }, + /** + * Display an error on the form. + * + * @param {string} message Should be a valid message key. + */ displayError: function ( message ) { var fb = this, closeButton = {}; @@ -220,10 +246,16 @@ this.$dialog.dialog( { buttons: closeButton } ); }, + /** + * Close the feedback form. + */ cancel: function () { this.$dialog.dialog( 'close' ); }, + /** + * Submit the feedback form. + */ submit: function () { var subject, message, fb = this; @@ -264,9 +296,9 @@ /** * Modify the display form, and then open it, focusing interface on the subject. - * @param {Object} optional prefilled contents for the feedback form. Object with properties: - * subject: {String} - * message: {String} + * @param {Object} [contents] Prefilled contents for the feedback form. + * @param {string} [contents.subject] The subject of the feedback + * @param {string} [contents.message] The content of the feedback */ launch: function ( contents ) { this.displayForm( contents ); -- 2.20.1