MarkTraceur has uploaded a new change for review.
https://gerrit.wikimedia.org/r/54510
Change subject: Added documentation for the LinkHandlers.
......................................................................
Added documentation for the LinkHandlers.
Change-Id: I054b2ad62ea3e0d43e0f493fca9dee4afd94718e
---
M js/lib/ext.core.LinkHandler.js
1 file changed, 157 insertions(+), 28 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/Parsoid
refs/changes/10/54510/1
diff --git a/js/lib/ext.core.LinkHandler.js b/js/lib/ext.core.LinkHandler.js
index a01b3be..6698078 100644
--- a/js/lib/ext.core.LinkHandler.js
+++ b/js/lib/ext.core.LinkHandler.js
@@ -15,27 +15,20 @@
Sanitizer = sanitizerLib.Sanitizer,
SanitizerConstants = sanitizerLib.SanitizerConstants;
-function WikiLinkHandler( manager, options ) {
- this.manager = manager;
- this.manager.addTransform( this.onWikiLink.bind( this ),
"WikiLinkHandler:onWikiLink", this.rank, 'tag', 'wikilink' );
- // create a new peg parser for image options..
- if ( !this.urlParser ) {
- // Actually the regular tokenizer, but we'll call it with the
- // img_options production only.
- WikiLinkHandler.prototype.urlParser = new PegTokenizer();
- }
-}
+/**
+ * @class LinkHandlerModule
+ * @singleton
+ */
-WikiLinkHandler.prototype.rank = 1.15; // after AttributeExpander
-
-/* ------------------------------------------------------------
- * This (overloaded) function does three different things:
- * - Extracts link text from attrs (when k === "").
- * As a performance micro-opt, only does if asked to (getLinkText)
- * - Updates existing rdfa type with an additional rdf-type,
- * if one is provided (rdfaType)
- * - Collates about, typeof, and linkAttrs into a new attr. array
- * ------------------------------------------------------------ */
+/**
+ * @method
+ * @private
+ * @param {KV[]} attrs
+ * @param {Function} getLinkText
+ * @param {string} rdfaType
+ * @param {KV[]} linkAttrs
+ * @returns {KV[]}
+ */
function buildLinkAttrs(attrs, getLinkText, rdfaType, linkAttrs) {
var newAttrs = [],
linkText = [],
@@ -82,6 +75,15 @@
};
}
+/**
+ * @method
+ * @private
+ * @param {string} link
+ * @returns {Object/null}
+ * @returns {string/null} return.colonEscape Either a colon that was at the
start of the string or null.
+ * @returns {string} return.interwikiPrefix
+ * @returns {string} return.article
+ */
function splitLink( link ) {
var match = link.match(/^(:)?([^:]+):(.*)$/);
if ( match ) {
@@ -95,6 +97,15 @@
}
}
+/**
+ * @method
+ * @private
+ *
+ * Get the content of an interwiki link.
+ *
+ * @param {Token} token
+ * @returns {string}
+ */
function interwikiContent( token ) {
// maybeContent is not set for links with pipetrick
var kv = Util.lookupKV( token.attribs, 'mw:maybeContent' ),
@@ -108,10 +119,40 @@
}
}
+/**
+ * @class
+ * @constructor
+ * @param {Object} manager
+ * @param {Object} options
+ */
+function WikiLinkHandler( manager, options ) {
+ this.manager = manager;
+ this.manager.addTransform( this.onWikiLink.bind( this ),
"WikiLinkHandler:onWikiLink", this.rank, 'tag', 'wikilink' );
+ // create a new peg parser for image options..
+ if ( !this.urlParser ) {
+ // Actually the regular tokenizer, but we'll call it with the
+ // img_options production only.
+ WikiLinkHandler.prototype.urlParser = new PegTokenizer();
+ }
+}
+
+/**
+ * @property {number} rank Specifies where in the queue this handler should be
called.
+ */
+WikiLinkHandler.prototype.rank = 1.15; // after AttributeExpander
+
// SSS FIXME: the attr called content should probably be called link-text?
+/**
+ * @method
+ *
+ * Main handler.
+ *
+ * @param {Token} token
+ * @param {Object} frame
+ * @param {Function} cb
+ */
WikiLinkHandler.prototype.onWikiLink = function ( token, frame, cb ) {
-
var j, maybeContent, about, possibleTags, property, newType,
hrefkv, saniContent, env = this.manager.env,
attribs = token.attribs,
@@ -264,6 +305,20 @@
}
};
+/**
+ * @method
+ * @private
+ *
+ * Render a file-embed link.
+ *
+ * @param {Token} token
+ * @param {Object} frame
+ * @param {Function} cb
+ * @param {string} fileName
+ * @param {string} title
+ * @returns {Object}
+ * @returns {Token[]} return.tokens
+ */
WikiLinkHandler.prototype.renderFile = function ( token, frame, cb, fileName,
title ) {
var env = this.manager.env,
// distinguish media types
@@ -482,11 +537,19 @@
}
};
-
-// Create an url for the scaled image src.
-// FIXME: This is just a dirty hack which will only ever work with the WMF
-// cluster configuration which creates an on-demand thumbnail when accessing a
-// width-prefixed image URL.
+/**
+ * @method
+ * @private
+ *
+ * Create an url for the scaled image src.
+ * FIXME: This is just a dirty hack which will only ever work with the WMF
+ * cluster configuration which creates an on-demand thumbnail when accessing a
+ * width-prefixed image URL.
+ *
+ * @param {string} key The image's name.
+ * @param {number} width
+ * @returns {string}
+ */
WikiLinkHandler.prototype.getThumbPath = function ( key, width ) {
var env = this.manager.env,
// Make a relative link.
@@ -495,7 +558,26 @@
return link + '/' + key + '?width=' + width;
};
-
+/**
+ * @method
+ * @private
+ *
+ * Render a thumbnail-embed link.
+ *
+ * @param {Token} token
+ * @param {Object} manager
+ * @param {Function} cb
+ * @param {string} title
+ * @param {string} fileName
+ * @param {string} caption
+ * @param {Object} oHash Object with image options
+ * @param {Object} options
+ * @param {Object} rdfaAttrs
+ * @param {boolean} rdfaAttrs.hasRdfaType
+ * @param {KV[]} rdfaAttrs.attribs
+ * @returns {Object}
+ * @returns {Token[]} return.tokens
+ */
WikiLinkHandler.prototype.renderThumb = function ( token, manager, cb, title,
fileName,
caption, oHash, options, rdfaAttrs )
{
@@ -683,6 +765,12 @@
return { tokens: thumb };
};
+/**
+ * @class
+ * @constructor
+ * @param {Object} manager
+ * @param {Object} options
+ */
function ExternalLinkHandler( manager, options ) {
this.manager = manager;
this.manager.addTransform( this.onUrlLink.bind( this ),
"ExternalLinkHandler:onUrlLink", this.rank, 'tag', 'urllink' );
@@ -699,11 +787,22 @@
this._reset();
}
+/**
+ * @method
+ * @private
+ */
ExternalLinkHandler.prototype._reset = function () {
this.linkCount = 1;
};
+/**
+ * @property {number} rank Specifies where in the queue this handler should
run.
+ */
ExternalLinkHandler.prototype.rank = 1.15;
+
+/**
+ * @property @private {Object} _imageExtensions Valid file extensions for
images.
+ */
ExternalLinkHandler.prototype._imageExtensions = {
'jpg': true,
'png': true,
@@ -711,6 +810,12 @@
'svg': true
};
+/**
+ * @method
+ * @private
+ * @param {string} href
+ * @returns {boolean}
+ */
ExternalLinkHandler.prototype._isImageLink = function ( href ) {
var bits = href.split( '.' );
return bits.length > 1 &&
@@ -718,6 +823,17 @@
href.match( /^https?:\/\//i );
};
+/**
+ * @method
+ *
+ * Handler for URL-only links (like "http://example.com";)
+ *
+ * @param {Token} token
+ * @param {Object} frame
+ * @param {Function} cb
+ * @param {Object} cb.value
+ * @param {Token[]} cb.value.tokens
+ */
ExternalLinkHandler.prototype.onUrlLink = function ( token, frame, cb ) {
var env = this.manager.env,
tagAttrs,
@@ -768,7 +884,13 @@
}
};
-// Bracketed external link
+/**
+ * @method
+ *
+ * Main handler for bracketed external links (like "[http://example.com
example]")
+ *
+ * @inheritdoc ExternalLinkHandler#onUrlLink
+ */
ExternalLinkHandler.prototype.onExtLink = function ( token, manager, cb ) {
var env = this.manager.env,
origHref = Util.lookup( token.attribs, 'href' ),
@@ -901,6 +1023,13 @@
}
};
+/**
+ * @method
+ *
+ * Handler for end-of-line tokens - links cannot span lines.
+ *
+ * @inheritdoc ExternalLinkHandler#onUrlLink
+ */
ExternalLinkHandler.prototype.onEnd = function ( token, manager, cb ) {
this._reset();
cb( { tokens: [ token ] } );
--
To view, visit https://gerrit.wikimedia.org/r/54510
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I054b2ad62ea3e0d43e0f493fca9dee4afd94718e
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/Parsoid
Gerrit-Branch: master
Gerrit-Owner: MarkTraceur <[email protected]>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
