Merge "EditCheck: Add more method documentation"

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 );
 };

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 );
 };

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 ) => {

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 () {

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 ) => {

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 [];