From 43b49080c901308335640861f0d86c66d47101dc Mon Sep 17 00:00:00 2001 From: Ed Sanders Date: Tue, 19 Nov 2024 13:41:38 +0000 Subject: [PATCH] EditCheck: Add more method documentation Change-Id: Ia250a0c09d700b0f8e78bf2ea9c17e35b8c40d6d --- editcheck/modules/EditCheckAction.js | 19 +++++++++++++++++++ editcheck/modules/EditCheckContextItem.js | 10 ++++++++++ editcheck/modules/EditCheckFactory.js | 12 ++++++++++++ editcheck/modules/EditCheckInspector.js | 3 +++ .../editchecks/AddReferenceEditCheck.js | 7 +++++++ editcheck/modules/init.js | 14 ++++++++++++++ 6 files changed, 65 insertions(+) diff --git a/editcheck/modules/EditCheckAction.js b/editcheck/modules/EditCheckAction.js index 219eef3443..8d0bccfb87 100644 --- a/editcheck/modules/EditCheckAction.js +++ b/editcheck/modules/EditCheckAction.js @@ -1,3 +1,12 @@ +/** + * EditCheckAction + * + * @param {Object} config + * @param {mw.editcheck.BaseEditCheck} check + * @param {ve.dm.SurfaceFragment[]} highlights Fragments to highlight + * @param {ve.dm.SurfaceFragment} selection Fragment to select when acting + * @param {jQuery|string|Function|OO.ui.HtmlSnippet} message Check message body + */ mw.editcheck.EditCheckAction = function MWEditCheckAction( config ) { this.check = config.check; this.highlights = config.highlights; @@ -7,10 +16,20 @@ mw.editcheck.EditCheckAction = function MWEditCheckAction( config ) { OO.initClass( mw.editcheck.EditCheckAction ); +/** + * Get the available choices + * + * @return {Object[]} + */ mw.editcheck.EditCheckAction.prototype.getChoices = function () { return this.check.getChoices( this ); }; +/** + * Get a description of the check + * + * @return {string} + */ mw.editcheck.EditCheckAction.prototype.getDescription = function () { return this.check.getDescription( this ); }; diff --git a/editcheck/modules/EditCheckContextItem.js b/editcheck/modules/EditCheckContextItem.js index 4f82dbf8a0..eed4f54bb0 100644 --- a/editcheck/modules/EditCheckContextItem.js +++ b/editcheck/modules/EditCheckContextItem.js @@ -64,6 +64,11 @@ ve.ui.EditCheckContextItem.prototype.renderBody = function () { ); }; +/** + * Close the context item + * + * @param {Object} data Window closing data + */ ve.ui.EditCheckContextItem.prototype.close = function ( data ) { // HACK: Un-suppress close button on mobile context if ( this.context.isMobile() ) { @@ -72,6 +77,11 @@ ve.ui.EditCheckContextItem.prototype.close = function ( data ) { this.data.callback( data, this.data ); }; +/** + * Handle click events on a choice button + * + * @param {string} choice Choice identifier, e.g. 'accept' or 'reject' + */ ve.ui.EditCheckContextItem.prototype.onChoiceClick = function ( choice ) { this.data.action.check.act( choice, this.data.action, this ); }; diff --git a/editcheck/modules/EditCheckFactory.js b/editcheck/modules/EditCheckFactory.js index 200f325880..2094577a60 100644 --- a/editcheck/modules/EditCheckFactory.js +++ b/editcheck/modules/EditCheckFactory.js @@ -14,6 +14,9 @@ OO.inheritClass( mw.editcheck.EditCheckFactory, OO.Factory ); /* Methods */ +/** + * @inheritdoc + */ mw.editcheck.EditCheckFactory.prototype.register = function ( constructor, name ) { name = name || ( constructor.static && constructor.static.name ); @@ -53,6 +56,15 @@ mw.editcheck.EditCheckFactory.prototype.getNamesByListener = function ( listener return this.checksByListener[ listener ]; }; +/** + * Create all checks actions for a given listener + * + * TODO: Rename to createAllActionsByListener + * + * @param {string} listener Listener name + * @param {ve.dm.Surface} surfaceModel Surface model + * @return {mw.editcheck.EditCheckActions[]} Actions, sorted by range + */ mw.editcheck.EditCheckFactory.prototype.createAllByListener = function ( listener, surfaceModel ) { const newChecks = []; this.getNamesByListener( listener ).forEach( ( checkName ) => { diff --git a/editcheck/modules/EditCheckInspector.js b/editcheck/modules/EditCheckInspector.js index 74f0b9b33f..8cb23dc3d7 100644 --- a/editcheck/modules/EditCheckInspector.js +++ b/editcheck/modules/EditCheckInspector.js @@ -135,6 +135,9 @@ ve.ui.EditCheckInspector.prototype.getReadyProcess = function ( data ) { }, this ); }; +/** + * @inheritdoc + */ ve.ui.EditCheckInspector.prototype.getActionProcess = function ( action ) { if ( action === '' ) { return new OO.ui.Process( function () { diff --git a/editcheck/modules/editchecks/AddReferenceEditCheck.js b/editcheck/modules/editchecks/AddReferenceEditCheck.js index 6f6c4c419e..db3ddece86 100644 --- a/editcheck/modules/editchecks/AddReferenceEditCheck.js +++ b/editcheck/modules/editchecks/AddReferenceEditCheck.js @@ -20,6 +20,13 @@ mw.editcheck.AddReferenceEditCheck.prototype.onBeforeSave = function ( surfaceMo } ); }; +/** + * Find content ranges which have been inserted + * + * @param {ve.dm.Document} documentModel + * @param {boolean} includeReferencedContent Include contents that already contains a reference + * @return {ve.Range[]} + */ mw.editcheck.AddReferenceEditCheck.prototype.findAddedContent = function ( documentModel, includeReferencedContent ) { // Broken out so a helper for tagging can call it const ranges = this.getModifiedContentRanges( documentModel ).filter( ( range ) => { diff --git a/editcheck/modules/init.js b/editcheck/modules/init.js index ecab91c8b0..4ed349f229 100644 --- a/editcheck/modules/init.js +++ b/editcheck/modules/init.js @@ -44,6 +44,13 @@ mw.editcheck.getContentRanges = function ( documentModel, range, covers ) { return ranges; }; +/** + * Check if the document has content needing a reference, for AddReferenceEditCheck + * + * @param {ve.dm.Document} documentModel + * @param {boolean} includeReferencedContent Include contents that already contains a reference + * @return {boolean} + */ mw.editcheck.hasAddedContentNeedingReference = function ( documentModel, includeReferencedContent ) { // helper for ve.init.mw.ArticleTarget save-tagging, keep logic below in-sync with AddReferenceEditCheck. // This is bypassing the normal "should this check apply?" logic for creation, so we need to manually @@ -55,6 +62,13 @@ mw.editcheck.hasAddedContentNeedingReference = function ( documentModel, include return check.findAddedContent( documentModel, includeReferencedContent ).length > 0; }; +/** + * Get content ranges which have been inserted + * + * @param {ve.dm.Document} documentModel + * @param {boolean} coveredNodesOnly Only include ranges which cover the whole of their node + * @return {ve.Range[]} + */ mw.editcheck.getModifiedRanges = function ( documentModel, coveredNodesOnly ) { if ( !documentModel.completeHistory.getLength() ) { return [];