MarkTraceur has uploaded a new change for review. https://gerrit.wikimedia.org/r/70925
Change subject: Add UWUI to the jsduck docs ...................................................................... Add UWUI to the jsduck docs Baby steps... Change-Id: I0d961ee3931abea6c5e0d765bfcc1348d3cdfbc4 --- M docs/external.js M docs/jsduck-config.json M resources/mw.UploadWizardUploadInterface.js 3 files changed, 81 insertions(+), 21 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/UploadWizard refs/changes/25/70925/1 diff --git a/docs/external.js b/docs/external.js index 56fafdd..0d3593c 100644 --- a/docs/external.js +++ b/docs/external.js @@ -36,6 +36,11 @@ */ /** + * @class jQuery + * A normal jQuery object. <http://api.jquery.com/Types/#jQuery> + */ + +/** * @class jQuery.Promise * <http://api.jquery.com/Types/#Promise> */ diff --git a/docs/jsduck-config.json b/docs/jsduck-config.json index 26fcd24..1d1aec8 100644 --- a/docs/jsduck-config.json +++ b/docs/jsduck-config.json @@ -9,6 +9,7 @@ "../resources/mw.ConfirmCloseWindow.js", "../resources/mw.UploadWizard.js", "../resources/mw.UploadWizardUpload.js", + "../resources/mw.UploadWizardUploadInterface.js", "../resources/mw.UploadWizardUploadList.js" ] } diff --git a/resources/mw.UploadWizardUploadInterface.js b/resources/mw.UploadWizardUploadInterface.js index 30c928a..df79365 100644 --- a/resources/mw.UploadWizardUploadInterface.js +++ b/resources/mw.UploadWizardUploadInterface.js @@ -1,11 +1,11 @@ -/** - * Create an interface fragment corresponding to a file input, suitable for Upload Wizard. - * @param upload - * @param div to insert file interface - * @param providedFile a File object that this ui component should use (optional) - */ ( function( mw, $j, undefined ) { - +/** + * @class + * Create an interface fragment corresponding to a file input, suitable for Upload Wizard. + * @param {mw.UploadWizardUpload} upload + * @param {HTMLDivElement} filesDiv Where to put the files + * @param {File} [providedFile] File object that this ui component should use + */ mw.UploadWizardUploadInterface = function( upload, filesDiv, providedFile ) { var _this = this; @@ -149,8 +149,8 @@ }, /** - * change the graphic indicator at the far end of the row for this file - * @param String statusClass: corresponds to a class mwe-upwiz-status which changes style of indicator. + * Change the graphic indicator at the far end of the row for this file + * @param {string} statusClass Changes style of indicator. */ showIndicator: function( statusClass ) { this.clearIndicator(); @@ -172,7 +172,7 @@ /** * Set the preview image on the file page for this upload. - * @param HTMLImageElement + * @param {HTMLImageElement} image */ setPreview: function( image ) { var $preview = $j( this.div ).find( '.mwe-upwiz-file-preview' ); @@ -186,8 +186,8 @@ /** * Set the status line for this upload with an internationalized message string. - * @param String msgKey: key for the message - * @param Array args: array of values, in case any need to be fed to the image. + * @param {string} msgKey + * @param {Array} args Values to be fed to the message. */ setStatus: function( msgKey, args ) { if ( args === undefined ) { @@ -200,7 +200,7 @@ /** * Set status line directly with a string - * @param {String} + * @param {string} s */ setStatusString: function( s ) { $j( this.div ).find( '.mwe-upwiz-file-status' ).html( s ).show(); @@ -215,7 +215,7 @@ /** * Put the visual state of an individual upload into "progress" - * @param fraction The fraction of progress. Float between 0 and 1 + * @param {number} fraction The fraction of progress. Float between 0 and 1. */ showTransportProgress: function( fraction ) { // if fraction available, update individual progress bar / estimates, etc. @@ -242,8 +242,8 @@ /** * Show that transport has failed - * @param String code: error code from API - * @param {String|Object} info: extra info + * @param {string} code Error code from API + * @param {string/Object} info Any extra info */ showError: function( code, info ) { this.showIndicator( 'error' ); @@ -267,7 +267,9 @@ this.setStatus( msgKey, args ); }, - + /** + * Initialize the file input. Calls mw.UploadWizardUpload#checkFile. + */ initFileInputCtrl: function() { var _this = this; _this.$fileInputCtrl.change( function() { @@ -285,7 +287,7 @@ /** * Get a list of the files from this file input, defaulting to the value from the input form - * @return {Array} of File objects + * @return {File[]} */ getFiles: function() { var files = []; @@ -304,7 +306,7 @@ /** * Get just the filename. - * @return {String} + * @return {string} */ getFilename: function() { if( this.providedFile && ! this.$fileInputCtrl.get(0).value ) { // default to the fileinput if it's defined. @@ -359,19 +361,33 @@ } }, + /** + * Utility function (TODO: Should we put this somewhere more global + * and/or remove it entirely?) + * @return {string} + */ URL: function() { return window.URL || window.webkitURL || window.mozURL; }, + /** + * @return {boolean} + */ isVideo: function() { return mw.fileApi.isAvailable() && mw.fileApi.isPreviewableVideo( this.upload.file ); }, + /** + * @return {boolean} + */ isPreviewable: function() { return mw.fileApi.isAvailable() && this.upload.file && mw.fileApi.isPreviewableFile( this.upload.file ); }, - // called once we have an image url + /** + * Called once we have an image url + * @param {string} url + */ loadImage: function( url ) { var image = document.createElement( 'img' ), _this = this; @@ -437,6 +453,11 @@ } }, + /** + * Signal an error + * @param {string} code Message key for the error + * @param {string/Array} info Extra information + */ fileChangedError: function( code, info ) { var filename = this.getFilename(); @@ -465,10 +486,19 @@ } }, + /** + * Signal that the filename wasn't parseable + * @param {string} filename + */ showUnparseableFilenameError: function( filename ) { this.showFilenameError( mw.msg( 'mwe-upwiz-unparseable-filename', filename ) ); }, + /** + * Signal that the extension wasn't acceptable + * @param {string} filename + * @param {string} extension + */ showBadExtensionError: function( filename, extension ) { var $errorMessage; // Check if firefogg should be recommended to be installed ( user selects an extension that can be converted) @@ -485,14 +515,26 @@ this.showFilenameError( $errorMessage ); }, + /** + * Signal that the file has no extension + * @param {string} filename + */ showMissingExtensionError: function( filename ) { this.showExtensionError( $j( '<p>' ).msg( 'mwe-upwiz-upload-error-bad-filename-no-extension' ) ); }, + /** + * Signal that the filename is wrong, but we don't know why + * @param {string} filename + */ showUnknownFilenameError: function( filename ) { this.showFilenameError( $j( '<p>' ).msg( 'mwe-upwiz-upload-error-unknown-filename-error', filename ) ); }, + /** + * Show an error with the extension of a filename (like .jpg, .png, etc.) + * @param {jQuery} $errorMessage + */ showExtensionError: function( $errorMessage ) { this.showFilenameError( $( '<div></div>' ).append( @@ -505,10 +547,19 @@ ); }, + /** + * Signal that the filename is a duplicate on the wiki + * @param {string} filename + * @param {string} basename + */ showDuplicateError: function( filename, basename ) { this.showFilenameError( $j( '<p>' ).msg( 'mwe-upwiz-upload-error-duplicate-filename-error', basename ) ); }, + /** + * Show an error with the filename given + * @param {jQuery} $text The DOM element(s) that represent the error + */ showFilenameError: function( $text ) { $( '<div>' ) .append( $text ) @@ -527,7 +578,7 @@ * or otherwise get it to do what you want. * It is helpful to sometimes move them to cover certain elements on the page, and * even to pass events like hover - * @param selector jquery-compatible selector, for a single element + * @param {string} selector jQuery-compatible selector, for a single element */ moveFileInputToCover: function( selector ) { var _this = this; @@ -563,6 +614,9 @@ update(); }, + /** + * Hide the file input so it's not actually visible to the user + */ hideFileInput: function() { if (this.moveFileInputInterval) { window.clearInterval(this.moveFileInputInterval); -- To view, visit https://gerrit.wikimedia.org/r/70925 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I0d961ee3931abea6c5e0d765bfcc1348d3cdfbc4 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
