MarkTraceur has uploaded a new change for review. https://gerrit.wikimedia.org/r/70919
Change subject: Clean up the jsduck docs after first two patches ...................................................................... Clean up the jsduck docs after first two patches The refactor patch (parent of this one) added a bunch of jsduck-y documentation, but it wasn't complete or error-free. This patch fixes all of that up, and now we have more things covered by our jsduck builder. Change-Id: I6845386dda6655a9ffed6cfa11c0a2f119ce9a12 --- M docs/external.js M docs/jsduck-config.json M resources/mw.UploadWizard.js M resources/mw.UploadWizardUpload.js M resources/mw.UploadWizardUploadList.js 5 files changed, 80 insertions(+), 35 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/UploadWizard refs/changes/19/70919/1 diff --git a/docs/external.js b/docs/external.js index 7a030d9..4bcb3e9 100644 --- a/docs/external.js +++ b/docs/external.js @@ -2,3 +2,39 @@ * @class mw * <https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw> */ + +/** + * @class File + * <http://www.w3.org/TR/FileAPI/#dfn-file> + */ + +/** + * @class Node + * <http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/core.html#ID-1950641247> + */ + +/** + * @class Element + * @extends Node + * <http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/core.html#ID-745549614> + */ + +/** + * @class HTMLImageElement + * @extends Element + */ + +/** + * @class HTMLCanvasElement + * @extends Element + */ + +/** + * @class HTMLDivElement + * @extends Element + */ + +/** + * @class jQuery.Promise + * <http://api.jquery.com/Types/#Promise> + */ diff --git a/docs/jsduck-config.json b/docs/jsduck-config.json index 259a28c..26fcd24 100644 --- a/docs/jsduck-config.json +++ b/docs/jsduck-config.json @@ -6,6 +6,9 @@ "--output": "./js", "--": [ "./external.js", - "../resources/mw.ConfirmCloseWindow.js" + "../resources/mw.ConfirmCloseWindow.js", + "../resources/mw.UploadWizard.js", + "../resources/mw.UploadWizardUpload.js", + "../resources/mw.UploadWizardUploadList.js" ] } diff --git a/resources/mw.UploadWizard.js b/resources/mw.UploadWizard.js index 4799c19..9c38847 100644 --- a/resources/mw.UploadWizard.js +++ b/resources/mw.UploadWizard.js @@ -1,10 +1,10 @@ -/** -* Object that reperesents the entire multi-step Upload Wizard -*/ - ( function( mw, $j, undefined ) { -mw.UploadWizard = function( config ) { +/** + * @class mw.UploadWizard + * Object that reperesents the entire multi-step Upload Wizard + */ +mw.UploadWizard = function ( config ) { this.uploads = new mw.UploadWizardUploadList(); this.api = new mw.Api( { url: config.apiUrl, ajax: { timeout: 0 } } ); @@ -386,7 +386,7 @@ * Get the own work and third party licensing deeds if they are needed. * * @since 1.2 - * @param {int|false} uploadsLength + * @param {number} uploadsLength * @return {Array} */ getLicensingDeeds: function( uploadsLength ) { @@ -1314,9 +1314,11 @@ }; /** + * @method + * @member mw * Check if a value is null, undefined, or the empty string. * - * @param {mixed} v Variable to be checked + * @param {Mixed} v Variable to be checked * @return {boolean} */ mw.isEmpty = function( v ) { diff --git a/resources/mw.UploadWizardUpload.js b/resources/mw.UploadWizardUpload.js index 5e43b20..f4046d3 100644 --- a/resources/mw.UploadWizardUpload.js +++ b/resources/mw.UploadWizardUpload.js @@ -1,16 +1,15 @@ -/** - * Represents the upload -- in its local and remote state. (Possibly those could be separate objects too...) - * This is our 'model' object if we are thinking MVC. Needs to be better factored, lots of feature envy with the UploadWizard - * states: - * 'new' 'transporting' 'transported' 'metadata' 'stashed' 'details' 'submitting-details' 'complete' 'error' - * should fork this into two -- local and remote, e.g. filename - */ ( function( $j, undefined ) { var fileNsId = mw.config.get( 'wgNamespaceIds' ).file; /** - * Constructor for objects representing uploads. The workhorse of this entire extension. + * @class mw.UploadWizardUpload + * + * Represents the upload -- in its local and remote state. (Possibly those could be separate objects too...) + * This is our 'model' object if we are thinking MVC. Needs to be better factored, lots of feature envy with the UploadWizard + * states: + * 'new' 'transporting' 'transported' 'metadata' 'stashed' 'details' 'submitting-details' 'complete' 'error' + * should fork this into two -- local and remote, e.g. filename * * The upload knows nothing of other uploads. It manages its own interface, and transporting its own data, to * the server. @@ -22,7 +21,8 @@ * On some browsers, the user may select multiple files. So upon such a 'filled' event, we add the first File to this Upload, and * then create other UploadWizardUpload objects from the individual Files, using the optional providedFile parameter. * - * @param {UploadWizard} wizard + * @constructor + * @param {mw.UploadWizard} wizard * @param {HTMLDivElement} filesDiv - where we will dump our the interfaces for uploads * @param {File} providedFile - optional; only used on browsers which support FileAPI. */ @@ -353,9 +353,11 @@ * * @param {string} the filename * @param {Array} of Files. usually one, can be more for multi-file select. - * @param {Function()} callback when ok, and upload object is ready - * @param {Function(String, Mixed)} callback when filename or contents in error. Signature of string code, mixed info - * @param {Function()} callback when resetting FileInput + * @param {Function} fileNameOk Callback to signal ok, and upload object is ready + * @param {Function} fileNameErr Callback for error + * @param {string} fileNameErr.signature Message key + * @param {Mixed} fileNameErr.info + * @param {Function} resetFileInput Callback to signal that we're resetting FileInput */ checkFile: function( filename, files, fileNameOk, fileNameErr, resetFileInput ) { var _this = this; @@ -715,10 +717,11 @@ /** * Get information about stashed images * See API documentation for prop=stashimageinfo for what 'props' can contain - * @param {Function} callback -- called with null if failure, with imageinfo data structure if success - * @param {Array} properties to extract - * @param {Number} optional, width of thumbnail. Will force 'url' to be added to props - * @param {Number} optional, height of thumbnail. Will force 'url' to be added to props + * @param {Function} callback + * @param {null/Object} callback.result Null if failure, else imageinfo data structure + * @param {string[]} props properties to extract + * @param {number} [width] Will force 'url' to be added to props + * @param {number} [height] Will force 'url' to be added to props */ getStashImageInfo: function( callback, props, width, height ) { var _this = this; @@ -766,10 +769,10 @@ * Get information about published images * (There is some overlap with getStashedImageInfo, but it's different at every stage so it's clearer to have separate functions) * See API documentation for prop=imageinfo for what 'props' can contain - * @param {Function} callback -- called with null if failure, with imageinfo data structure if success - * @param {Array} properties to extract - * @param {Number} optional, width of thumbnail. Will force 'url' to be added to props - * @param {Number} optional, height of thumbnail. Will force 'url' to be added to props + * @param {Function} callback Called with null if failure, with imageinfo data structure if success + * @param {Array} props Properties to extract + * @param {number} [width] For thumbnail. Will force 'url' to be added to props + * @param {number} [height] For thumbnail. Will force 'url' to be added to props */ getImageInfo: function( callback, props, width, height ) { var _this = this; @@ -927,7 +930,7 @@ /** * Return the orientation of the image in degrees. Relies on metadata that * may have been extracted at filereader stage, or after the upload when we fetch metadata. Default returns 0. - * @return {Integer} orientation in degrees: 0, 90, 180 or 270 + * @return {number} orientation in degrees: 0, 90, 180 or 270 */ getOrientationDegrees: function() { var orientation = 0; @@ -1068,9 +1071,9 @@ /** * Return an element suitable for the preview of a certain size. Uses canvas when possible * @param {HTMLImageElement} - * @param {Integer} width - * @param {Integer} height - * @return {HTMLCanvasElement|HTMLImageElement} + * @param {number} width + * @param {number} height + * @return {HTMLCanvasElement/HTMLImageElement} */ getScaledImageElement: function( image, width, height ) { if ( width === undefined || width === null || width <= 0 ) { @@ -1097,11 +1100,12 @@ setThumbnail: function( selector, width, height, isLightBox ) { var _this = this; + var placed = false; + /** * This callback will add an image to the selector, using in-browser scaling if necessary - * @param {HTMLImageElement} + * @param {HTMLImageElement} image */ - var placed = false; var placeImageCallback = function( image ) { if ( image === null ) { $j( selector ).addClass( 'mwe-upwiz-file-preview-broken' ); diff --git a/resources/mw.UploadWizardUploadList.js b/resources/mw.UploadWizardUploadList.js index c3a416f..8c1a06e 100644 --- a/resources/mw.UploadWizardUploadList.js +++ b/resources/mw.UploadWizardUploadList.js @@ -8,7 +8,7 @@ * Class for managing the list of UploadWizardUpload objects that we have in * the interface at any given time. * @constructor - * @param {mw.UploadWizardUpload[]/mwUploadWizardUpload} initialUploads + * @param {mw.UploadWizardUpload[]/mw.UploadWizardUpload} initialUploads */ mw.UploadWizardUploadList = function ( initialUploads ) { var i; -- To view, visit https://gerrit.wikimedia.org/r/70919 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I6845386dda6655a9ffed6cfa11c0a2f119ce9a12 Gerrit-PatchSet: 1 Gerrit-Project: mediawiki/extensions/UploadWizard Gerrit-Branch: master Gerrit-Owner: MarkTraceur <[email protected]> _______________________________________________ MediaWiki-commits mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
