Cscott has uploaded a new change for review.
https://gerrit.wikimedia.org/r/231492
Change subject: doc: add some WTS classes to the generated documentation.
......................................................................
doc: add some WTS classes to the generated documentation.
Change-Id: I71fbe3f142ac47c5e66a3fe2ffd119e6e36ac1f5
---
M .jsduck/categories.json
M jsduck.json
M lib/domTraverser.js
M lib/ext.core.LinkHandler.js
M lib/mediawiki.ApiRequest.js
M lib/mediawiki.DOMUtils.js
M lib/mediawiki.SelectiveSerializer.js
M lib/mediawiki.TokenTransformManager.js
M lib/mediawiki.WikitextSerializer.js
M lib/wts.ConstrainedText.js
M lib/wts.SerializerState.js
M tests/parserTests.js
12 files changed, 202 insertions(+), 55 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/services/parsoid
refs/changes/92/231492/1
diff --git a/.jsduck/categories.json b/.jsduck/categories.json
index e261dc8..1c9ae4a 100644
--- a/.jsduck/categories.json
+++ b/.jsduck/categories.json
@@ -45,6 +45,19 @@
]
},
{
+ "name": "HTML to Wikitext",
+ "classes": [
+ "WikitextSerializer",
+ "SerializerState",
+ "ConstrainedText",
+ "RegExpConstrainedText",
+ "AutoURLLinkText",
+ "ExtLinkText",
+ "MagicLinkText",
+ "WikiLinkText"
+ ]
+ },
+ {
"name": "Tokens",
"classes": [
"CommentTk",
diff --git a/jsduck.json b/jsduck.json
index 92cccda..f050562 100644
--- a/jsduck.json
+++ b/jsduck.json
@@ -21,8 +21,11 @@
"lib/mediawiki.Title.js",
"lib/mediawiki.Util.js",
"lib/mediawiki.WikiConfig.js",
+ "lib/mediawiki.WikitextSerializer.js",
"lib/mediawiki.parser.defines.js",
"lib/mediawiki.parser.environment.js",
+ "lib/wts.ConstrainedText.js",
+ "lib/wts.SerializerState.js",
"api/ParsoidService.js"
]
}
diff --git a/lib/domTraverser.js b/lib/domTraverser.js
index a731fe0..0705d92 100644
--- a/lib/domTraverser.js
+++ b/lib/domTraverser.js
@@ -10,7 +10,10 @@
* There might be scenarios where a post-order depth-first traversal might be
better.
* We should add an option for doing this.
*
- * @param node {HTMLNode} The node to be traversed
+ * @class
+ * @constructor
+ * @param {MWParserEnvironment} env
+ * @param {boolean} skipCheckIfAttached
*/
function DOMTraverser(env, skipCheckIfAttached) {
this.handlers = [];
diff --git a/lib/ext.core.LinkHandler.js b/lib/ext.core.LinkHandler.js
index e2ea473..cc5a1d6 100644
--- a/lib/ext.core.LinkHandler.js
+++ b/lib/ext.core.LinkHandler.js
@@ -767,7 +767,7 @@
*
* @private
* @param {Object} info
- * @param {string/null} info.thumburl The URL for a thumbnail
+ * @param {string|null} info.thumburl The URL for a thumbnail
* @param {string} info.url The base URL for the image
*/
function getPath(info) {
diff --git a/lib/mediawiki.ApiRequest.js b/lib/mediawiki.ApiRequest.js
index 4ecf361..01eeb37 100644
--- a/lib/mediawiki.ApiRequest.js
+++ b/lib/mediawiki.ApiRequest.js
@@ -182,7 +182,7 @@
/**
* @method
* @private
- * @param {Error/null} error
+ * @param {Error|null} error
* @param {string} data wikitext / html / metadata
*/
ApiRequest.prototype._processListeners = function(error, data) {
@@ -219,7 +219,7 @@
/**
* @method
* @private
- * @param {Error/null} error
+ * @param {Error|null} error
* @param {Object} response The API response object, with error code
* @param {string} body The body of the response from the API
*/
@@ -269,7 +269,7 @@
*
* @method
* @private
- * @param {Error/null} error
+ * @param {Error|null} error
* @param {string} body The body of the response from the API
*/
ApiRequest.prototype._handleBody = function(error, body) {
@@ -834,7 +834,9 @@
* @constructor
* @param {MWParserEnvironment} env
* @param {string} filename
- * @param @optional {Object} dims
+ * @param {Object} [dims]
+ * @param {number} [dims.width]
+ * @param {number} [dims.height]
*/
function ImageInfoRequest(env, filename, dims) {
ApiRequest.call(this, env, null);
diff --git a/lib/mediawiki.DOMUtils.js b/lib/mediawiki.DOMUtils.js
index 06ab37c..9b5880a 100644
--- a/lib/mediawiki.DOMUtils.js
+++ b/lib/mediawiki.DOMUtils.js
@@ -636,7 +636,7 @@
* HTML element (like table or p)
*
* @param {Object} dp
- * @param {string/undefined} dp.stx
+ * @param {string|undefined} [dp.stx]
*/
hasLiteralHTMLMarker: function(dp) {
return dp.stx === 'html';
@@ -1614,8 +1614,8 @@
* Wrap text and comment nodes in a node list into spans, so that all
* top-level nodes are elements.
*
- * @param array List of DOM nodes to wrap, mix of node types
- * @return array List of *element* nodes
+ * @param {Node[]} nodes List of DOM nodes to wrap, mix of node types
+ * @return {Node[]} List of *element* nodes
*/
addSpanWrappers: function(nodes) {
var textCommentAccum = [];
@@ -1670,9 +1670,9 @@
* token processing while preserving token stream semantics as if
* the DOM had been converted to tokens.
*
- * @param nodes List of DOM nodes that need to be tunneled through
- * @param opts The pipeline opts that generated the DOM
- * @return array List of token representatives
+ * @param {Node[]} nodes List of DOM nodes that need to be tunneled
through
+ * @param {Object} opts The pipeline opts that generated the DOM
+ * @return {Array} List of token representatives
*/
getWrapperTokens: function(nodes, opts) {
@@ -2430,7 +2430,7 @@
* re-serializing it to HTML. Ideally, the parser would normalize inter-tag
* whitespace for us. For now, we fake that by simply stripping all newlines.
*
- * @param source {string}
+ * @param {string} source
* @return {string}
*/
DOMUtils.normalizeHTML = function(source) {
diff --git a/lib/mediawiki.SelectiveSerializer.js
b/lib/mediawiki.SelectiveSerializer.js
index 5be40dd..9bc988e 100644
--- a/lib/mediawiki.SelectiveSerializer.js
+++ b/lib/mediawiki.SelectiveSerializer.js
@@ -20,8 +20,8 @@
* serialization method, only reporting the serialized wikitext for parts of
* the page that changed. Else, we fall back to serializing the whole DOM.
*
- * @param options {Object} Options for the serializer.
- * @param options.env {MWParserEnvironment}
+ * @param {Object} options Options for the serializer.
+ * @param {MWParserEnvironment} options.env
*/
var SelectiveSerializer = function(options) {
this.env = options.env || { conf: { parsoid: {} } };
diff --git a/lib/mediawiki.TokenTransformManager.js
b/lib/mediawiki.TokenTransformManager.js
index 591079e..273f3f7 100644
--- a/lib/mediawiki.TokenTransformManager.js
+++ b/lib/mediawiki.TokenTransformManager.js
@@ -511,12 +511,18 @@
* templates, images, links and other async expansions (see the transform
* recipe mediawiki.parser.js) are processed.
*
- * @param tokens {Array}: Chunk of tokens, potentially with rank and other
- * meta information associated with it.
- * @param parentCB {Function}: callback for asynchronous results
- * @returns {Object}: { tokens: [], async: falsy or the tail TokenAccumulator }
* The returned chunk is fully expanded for this phase, and the rank set
* to reflect this.
+ *
+ * @param {Array} tokens
+ * Chunk of tokens, potentially with rank and other meta information
+ * associated with it.
+ * @param {Function} parentCB
+ * Callback for asynchronous results
+ * @returns {Object}
+ * @returns {Array} return.tokens
+ * @returns {boolean|TokenAccumulator} return.async
+ * A falsy value or the tail TokenAccumulator
*/
AsyncTokenTransformManager.prototype.transformTokens = function(tokens,
parentCB) {
diff --git a/lib/mediawiki.WikitextSerializer.js
b/lib/mediawiki.WikitextSerializer.js
index b052fe7..d66c878 100644
--- a/lib/mediawiki.WikitextSerializer.js
+++ b/lib/mediawiki.WikitextSerializer.js
@@ -46,7 +46,10 @@
*
* @class
* @constructor
- * @param options {Object} List of options for serialization
+ * @param {Object} options List of options for serialization
+ * @param {MWParserEnvironment} options.env
+ * @param {boolean} [options.rtTestMode]
+ * @param {string} [options.logType="trace/wts"]
*/
function WikitextSerializer(options) {
this.options = options;
diff --git a/lib/wts.ConstrainedText.js b/lib/wts.ConstrainedText.js
index 898325c..a31f4f8 100644
--- a/lib/wts.ConstrainedText.js
+++ b/lib/wts.ConstrainedText.js
@@ -1,4 +1,4 @@
-/**
+/*
* Chunk-based serialization support.
*
* Keeping wikitext output in `ConstrainedText` chunks allows us to
@@ -17,7 +17,7 @@
var WTSUtils = require('./wts.utils.js').WTSUtils;
var util = require('util');
-/**
+/*
* This adds necessary escapes to a line of chunks. We provide
* the `ConstrainedText#escape` function with its left and right
* context, and it can determine what escapes are needed.
@@ -25,6 +25,7 @@
* The `line` parameter is an array of `ConstrainedText` *chunks*
* which make up a line (or part of a line, in some cases of nested
* processing).
+ * @private
*/
var escapeLine = function(line, cb) {
// The left context will be precise (that is, it is the result
@@ -75,7 +76,20 @@
* context or wikitext boundary restrictions for proper escaping.
* The chunk is serialized with the `escape` method, which might
* alter the wikitext in order to ensure it doesn't run together
- * with its context (usually by adding <nowiki> tags).
+ * with its context (usually by adding `<nowiki>` tags).
+ * @class ConstrainedText
+ */
+/**
+ * @method constructor
+ * @param {Object} args Options
+ * @param {string} args.text The text string associated with this chunk.
+ * @param {Node} args.node The DOM {@link Node} associated with this chunk.
+ * @param {string} [args.prefix]
+ * The prefix string to add if the start of the chunk doesn't match its
+ * constraints.
+ * @param {string} [args.suffix]
+ * The suffix string to add if the end of the chunk doesn't match its
+ * constraints.
*/
var ConstrainedText = function ConstrainedText(args) {
this.text = args.text;
@@ -86,8 +100,15 @@
this.suffix = args.suffix;
}
};
-/** Ensure that the argument, which is perhaps a string, is a instance of
- * `ConstrainedText`. */
+/**
+ * Ensure that the argument `o`, which is perhaps a string, is a instance of
+ * `ConstrainedText`.
+ * @param {string|ConstrainedText} o
+ * @param {Node} node
+ * The DOM {@link Node} corresponding to `o`.
+ * @return {ConstrainedText}
+ * @static
+ */
ConstrainedText.cast = function(o, node) {
if (o instanceof ConstrainedText) { return o; }
return new ConstrainedText({ text: o, node: node });
@@ -97,35 +118,57 @@
* list of chunks, to determine the proper escape prefix/suffix.
* Returns an object with a `text` property as well as optional
* `prefix` and 'suffix' properties giving desired escape strings.
+ * @param {Object} state
+ * @return {Object}
+ * @return {string} return.text
+ * @return {string} [return.prefix]
+ * @return {string} [return.suffix]
*/
ConstrainedText.prototype.escape = function(state) {
// default implementation: no escaping, no prefixes or suffixes.
return { text: this.text, prefix: this.prefix, suffix: this.suffix };
};
-// Simple equality. This enforces type equality (ie subclasses are not equal)
+/**
+ * Simple equality. This enforces type equality (ie subclasses are not equal)
+ * @param {Object} ct
+ * @return {boolean}
+ */
ConstrainedText.prototype.equals = function(ct) {
return this === ct ||
(this.constructor === ConstrainedText &&
ct.constructor === ConstrainedText &&
this.text === ct.text);
};
-// Useful shortcut: execute a regular expression on the raw wikitext.
+/**
+ * Useful shortcut: execute a regular expression on the raw wikitext.
+ * @param {RegExp} re
+ * @return {Array|null}
+ * An Array containing the matched results or null if there were no matches.
+ */
ConstrainedText.prototype.match = function(re) {
return this.text.match(re);
};
-// SelSer support: when we come across an unmodified node in during
-// selective serialization, we know we can use the original wikitext
-// for that node unmodified. *But* there may be boundary conditions
-// on the left and right sides of the selser'ed text which are going
-// to require escaping.
-//
-// So rather than turning the node into a plain old `ConstrainedText`
-// chunk, allow subclasses of `ConstrainedText` to register as potential
-// handlers of selser nodes. A selser'ed magic link, for example,
-// will then turn into a `MagicLinkText` and thus be able to enforce
-// the proper boundary constraints.
-
+/**
+ * SelSer support: when we come across an unmodified node in during
+ * selective serialization, we know we can use the original wikitext
+ * for that node unmodified. *But* there may be boundary conditions
+ * on the left and right sides of the selser'ed text which are going
+ * to require escaping.
+ *
+ * So rather than turning the node into a plain old `ConstrainedText`
+ * chunk, allow subclasses of `ConstrainedText` to register as potential
+ * handlers of selser nodes. A selser'ed magic link, for example,
+ * will then turn into a `MagicLinkText` and thus be able to enforce
+ * the proper boundary constraints.
+ * @method fromSelSer
+ * @static
+ * @param {string} text
+ * @param {Node} node
+ * @param {Object} dataParsoid
+ * @param {MWParserEnvironment} env
+ * @param {Object} opts
+ */
// Main dispatch point: iterate through registered subclasses, asking
// each if they can handle this node (by invoking `_fromSelSer`).
ConstrainedText.fromSelSer = function(text, node, dataParsoid, env, opts) {
@@ -146,12 +189,17 @@
throw new Error("Should never happen.");
};
-// Base case: the given node type does not correspond to a special
-// `ConstrainedText` subclass. We still have to be careful: the leftmost
-// (rightmost) children of `node` may still be exposed to our left (right)
-// context. If so (ie, their DSR bounds coincide) split the selser text
-// and emit multiple `ConstrainedText` chunks to preserve the proper
-// boundary conditions.
+/**
+ * Base case: the given node type does not correspond to a special
+ * `ConstrainedText` subclass. We still have to be careful: the leftmost
+ * (rightmost) children of `node` may still be exposed to our left (right)
+ * context. If so (ie, their DSR bounds coincide) split the selser text
+ * and emit multiple `ConstrainedText` chunks to preserve the proper
+ * boundary conditions.
+ * @method
+ * @static
+ * @private
+ */
ConstrainedText._fromSelSer = function(text, node, dataParsoid, env, opts) {
// look at leftmost and rightmost children, it may be that we need
// to turn these into ConstrainedText chunks in order to preserve
@@ -215,7 +263,12 @@
};
ConstrainedText._types = [ ConstrainedText ];
-// Add a subtype to the list of types we attempt `fromSelSer` with.
+/**
+ * Add a subtype to the list of types we attempt `fromSelSer` with.
+ * @static
+ * @method
+ * @param {ConstrainedText} subtype A subclass of {@link ConstrainedText}
+ */
ConstrainedText.register = function(subtype) {
ConstrainedText._types.push(subtype);
};
@@ -232,6 +285,13 @@
/**
* This subclass allows specification of a regular expression for
* acceptable (or prohibited) leading (and/or trailing) contexts.
+ * @class
+ * @extends ConstrainedText
+ * @constructor
+ * @inheritdoc
+ * @param {Object} args
+ * @param {RegExp} args.goodPrefix
+ * @param {RegExp} args.goodSuffix
*/
var RegExpConstrainedText = function RegExpConstrainedText(args) {
RegExpConstrainedText.super_.call(this, args);
@@ -256,7 +316,17 @@
return result;
};
-// WikiLinks
+/**
+ * An internal wiki link, like `[[Foo]]`.
+ * @class
+ * @extends RegExpConstrainedText
+ * @constructor
+ * @param {string} text
+ * @param {Node} node
+ * @param {WikiConfig} wikiConfig
+ * @param {string} type
+ * The type of the link, as described by the `rel` attribute.
+ */
var WikiLinkText = function WikiLinkText(text, node, wikiConfig, type) {
// category links/external links/images don't use link trails or
prefixes
var noTrails = !/^mw:(Wiki|Ext)Link$/.test(type);
@@ -293,6 +363,17 @@
}
};
+/**
+ * An external link, like `[http://example.com]`.
+ * @class
+ * @extends ConstrainedText
+ * @constructor
+ * @param {string} text
+ * @param {Node} node
+ * @param {WikiConfig} wikiConfig
+ * @param {string} type
+ * The type of the link, as described by the `rel` attribute.
+ */
var ExtLinkText = function ExtLinkText(text, node, wikiConfig, type) {
ExtLinkText.super_.call(this, {
text: text,
@@ -320,6 +401,14 @@
// include ')' as well.
var AUTOURL_BAD_NOPAREN = new RegExp("^" + NOT_LTGT + "[" + TRAILING_PUNCT +
"\\)]*[" + EXT_LINK_URL_CLASS + TRAILING_PUNCT + "\\)]");
+/**
+ * An autolink to an external resource, like `http://example.com`.
+ * @class
+ * @extends RegExpConstrainedText
+ * @constructor
+ * @param {string} url
+ * @param {Node} node
+ */
var AutoURLLinkText = function AutoURLLinkText(url, node) {
AutoURLLinkText.super_.call(this, {
text: url,
@@ -337,6 +426,14 @@
}
};
+/**
+ * An autolink to an RFC/PMID/ISBN, like `RFC 1234`.
+ * @class
+ * @extends RegExpConstrainedText
+ * @constructor
+ * @param {string} text
+ * @param {Node} node
+ */
var MagicLinkText = function MagicLinkText(text, node) {
MagicLinkText.super_.call(this, {
text: text,
diff --git a/lib/wts.SerializerState.js b/lib/wts.SerializerState.js
index ec592b3..579c5da 100644
--- a/lib/wts.SerializerState.js
+++ b/lib/wts.SerializerState.js
@@ -120,6 +120,10 @@
this._stack.pop();
};
+/**
+ * @class
+ * @constructor
+ */
function SerializerState(serializer, options) {
this.env = serializer.env;
this.serializer = serializer;
@@ -132,6 +136,8 @@
var SSP = SerializerState.prototype;
+/**
+ */
SSP.resetCurrLine = function(node) {
this.currLine = {
text: '',
@@ -143,13 +149,17 @@
};
};
+/**
+ */
SSP.flushLine = function(cb) {
escapeLine(this.currLine.chunks, cb);
this.currLine.chunks.length = 0;
};
-// Serialize the children of a DOM node, sharing the global serializer state.
-// Typically called by a DOM-based handler to continue handling its children.
+/**
+ * Serialize the children of a DOM node, sharing the global serializer state.
+ * Typically called by a DOM-based handler to continue handling its children.
+ */
SSP.serializeChildren = function(node, chunkCB, wtEscaper) {
try {
// TODO gwicke: use nested WikitextSerializer instead?
@@ -188,17 +198,23 @@
}
};
+/**
+ */
SSP.getOrigSrc = function(start, end) {
console.assert(this.selserMode);
return this.env.page.src.substring(start, end);
};
+/**
+ */
SSP.updateModificationFlags = function(node) {
this.prevNodeUnmodified = this.currNodeUnmodified;
this.currNodeUnmodified = false;
this.prevNode = node;
};
+/**
+ */
SSP.emitSep = function(sep, node, cb, debugPrefix) {
// Replace newlines if we're in a single-line context
if (this.singleLineContext.enforced()) {
@@ -219,6 +235,8 @@
function() { return JSON.stringify(sep); });
};
+/**
+ */
SSP.emitSepAndOutput = function(res, node, cb, logPrefix) {
res = ConstrainedText.cast(res, node);
@@ -441,6 +459,8 @@
return bits;
};
+/**
+ */
SSP.serializeLinkChildrenToString = function(node, wtEscaper, onSOL) {
this.inLink = true;
var out = this.serializeChildrenToString(node, wtEscaper, onSOL);
diff --git a/tests/parserTests.js b/tests/parserTests.js
index 3babb7c..fe8212a 100755
--- a/tests/parserTests.js
+++ b/tests/parserTests.js
@@ -407,8 +407,8 @@
* @param {Object} item
* @param {Node} body
* @param {Function} processWikitextCB
- * @param {Error/null} processWikitextCB.err
- * @param {string/null} processWikitextCB.res
+ * @param {Error|null} processWikitextCB.err
+ * @param {string|null} processWikitextCB.res
*/
ParserTests.prototype.convertHtml2Wt = function(options, mode, item, body,
processWikitextCB) {
var startsAtWikitext = mode === 'wt2wt' || mode === 'wt2html' || mode
=== 'selser';
@@ -641,7 +641,7 @@
* @param {Object} item
* @param {Node} body
* @param {Function} cb
- * @param {Error/null} cb.err
+ * @param {Error|null} cb.err
* @param {Node} cb.body
* @param {Array} cb.changelist
*/
@@ -858,8 +858,8 @@
* @param {string} mode
* @param {string} wikitext
* @param {Function} processHtmlCB
- * @param {Error/null} processHtmlCB.err
- * @param {Node/null} processHtmlCB.doc
+ * @param {Error|null} processHtmlCB.err
+ * @param {Node|null} processHtmlCB.doc
*/
ParserTests.prototype.convertWt2Html = function(mode, wikitext, processHtmlCB)
{
this.env.setPageSrcInfo(wikitext);
@@ -1118,7 +1118,7 @@
* @method
* @param {string} title
* @param {Array} comments
- * @param {Object/null} iopts Options from the test file
+ * @param {Object|null} iopts Options from the test file
* @param {Object} options
* @param {Object} actual
* @param {Object} expected
--
To view, visit https://gerrit.wikimedia.org/r/231492
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I71fbe3f142ac47c5e66a3fe2ffd119e6e36ac1f5
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/services/parsoid
Gerrit-Branch: master
Gerrit-Owner: Cscott <[email protected]>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
