- * 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