jenkins-bot has submitted this change and it was merged. Change subject: Resurrect JSDuck configuration. ......................................................................
Resurrect JSDuck configuration. Change-Id: I37f761543e4c32c23261bf8ad1302539bebacb3b --- M .gitignore A .jsduck/CustomTags.rb A .jsduck/categories.json R .jsduck/external.js A .jsduck/guides.json M api/ParsoidService.js D doc.guides.json M guides/apiuse/README.md M guides/devsetup/README.md M guides/setup/README.md D jsduck-conf.json A jsduck.json M lib/LogData.js M lib/Logger.js M lib/ParsoidLogger.js M lib/jsapi.js M lib/mediawiki.DOMUtils.js M lib/mediawiki.ParsoidConfig.js M lib/mediawiki.Title.js M lib/mediawiki.Util.js M lib/mediawiki.WikiConfig.js M lib/mediawiki.parser.defines.js M lib/mediawiki.parser.environment.js M package.json R specs/apiv2.yaml 25 files changed, 539 insertions(+), 234 deletions(-) Approvals: Arlolra: Looks good to me, approved jenkins-bot: Verified diff --git a/.gitignore b/.gitignore index 2020305..05510a3 100644 --- a/.gitignore +++ b/.gitignore @@ -16,7 +16,7 @@ tests/client/config.js tests/server/node_modules tests/server/server.settings.js -doc +/docs tests/server/pages.db tests/client/config.js coverage/ diff --git a/.jsduck/CustomTags.rb b/.jsduck/CustomTags.rb new file mode 100644 index 0000000..5e32a89 --- /dev/null +++ b/.jsduck/CustomTags.rb @@ -0,0 +1,134 @@ +# Custom tags for JSDuck 5.x +# See also: +# - https://github.com/senchalabs/jsduck/wiki/Tags +# - https://github.com/senchalabs/jsduck/wiki/Custom-tags +# - https://github.com/senchalabs/jsduck/wiki/Custom-tags/7f5c32e568eab9edc8e3365e935bcb836cb11f1d +require 'jsduck/tag/tag' + +class CommonTag < JsDuck::Tag::Tag + def initialize + @html_position = POS_DOC + 0.1 + @repeatable = true + end + + def parse_doc(scanner, position) + if @multiline + return { :tagname => @tagname, :doc => :multiline } + else + text = scanner.match(/.*$/) + return { :tagname => @tagname, :doc => text } + end + end + + def process_doc(context, tags, position) + context[@tagname] = tags + end + + def format(context, formatter) + context[@tagname].each do |tag| + tag[:doc] = formatter.format(tag[:doc]) + end + end +end + +class SourceTag < CommonTag + def initialize + @tagname = :source + @pattern = "source" + super + end + + def to_html(context) + context[@tagname].map do |source| + <<-EOHTML + <h3 class='pa'>Source</h3> + #{source[:doc]} + EOHTML + end.join + end +end + +class UntilTag < CommonTag + def initialize + @tagname = :until + @pattern = "until" + super + end + + def to_html(context) + <<-EOHTML + <h3>Until</h3> + <div class="signature-box"><p> + This method provides <strong>browser compatibility</strong> for: + #{ context[@tagname].map {|tag| tag[:doc] }.join("\n") } + </p></div> + EOHTML + end +end + +class SeeTag < CommonTag + def initialize + @tagname = :see + @pattern = "see" + super + end + + def format(context, formatter) + position = context[:files][0] + context[@tagname].each do |tag| + tag[:doc] = '<li>' + render_long_see(tag[:doc], formatter, position) + '</li>' + end + end + + def to_html(context) + <<-EOHTML + <h3 class="pa">Related</h3> + <ul> + #{ context[@tagname].map {|tag| tag[:doc] }.join("\n") } + </ul> + EOHTML + end + + def render_long_see(tag, formatter, position) + if tag =~ /\A([^\s]+)( .*)?\Z/m + name = $1 + doc = $2 ? ': ' + $2 : '' + return formatter.format("{@link #{name}} #{doc}") + else + JsDuck::Logger.warn(nil, 'Unexpected @see argument: "'+tag+'"', position) + return tag + end + end +end + +class ContextTag < CommonTag + def initialize + @tagname = :this + @pattern = 'this' + super + end + + def format(context, formatter) + position = context[:files][0] + context[@tagname].each do |tag| + tag[:doc] = render_long_context(tag[:doc], formatter, position) + end + end + + def to_html(context) + <<-EOHTML + <h3 class="pa">Context</h3> + #{ context[@tagname].last[:doc] } + EOHTML + end + + def render_long_context(tag, formatter, position) + if tag =~ /\A([^\s]+)/m + name = $1 + return formatter.format("`this` : {@link #{name}}") + else + JsDuck::Logger.warn(nil, 'Unexpected @this argument: "'+tag+'"', position) + return tag + end + end +end diff --git a/.jsduck/categories.json b/.jsduck/categories.json new file mode 100644 index 0000000..56b89e7 --- /dev/null +++ b/.jsduck/categories.json @@ -0,0 +1,99 @@ +[ + { + "name": "Parsoid", + "groups": [ + { + "name": "Package Interface", + "classes": [ + "Parsoid", + "PDoc", + "PNodeList", + "PNode", + "PExtLink", + "PHeading", + "PHtmlEntity", + "PTemplate", + "PWikiLink" + ] + }, + { + "name": "Server Interface", + "classes": [ + "ParsoidService" + ] + }, + { + "name": "Core", + "classes": [ + "DOMUtils", + "MWParserEnvironment", + "Namespace", + "ParsoidConfig", + "Title", + "Util", + "WikiConfig" + ] + }, + { + "name": "Tokens", + "classes": [ + "CommentTk", + "EndTagTk", + "KV", + "NlTk", + "Params", + "SelfclosingTagTk", + "TagTk", + "Token" + ] + }, + { + "name": "Logging", + "classes": [ + "LogData", + "Logger", + "ParsoidLogger" + ] + } + ] + }, + { + "name": "Upstream", + "groups": [ + { + "name": "DOM", + "classes": [ + "CharacterData", + "CommentNode", + "Document", + "Element", + "Node", + "TextNode" + ] + }, + { + "name": "Node", + "classes": [ + "EventEmitter", + "Response", + "Request" + ] + }, + { + "name": "JavaScript", + "classes": [ + "Array", + "Boolean", + "Date", + "Function", + "Map", + "Number", + "Object", + "RegExp", + "Set", + "String" + ] + } + ] + } +] diff --git a/doc.basicTypes.js b/.jsduck/external.js similarity index 63% rename from doc.basicTypes.js rename to .jsduck/external.js index 445c537..25e4d0b 100644 --- a/doc.basicTypes.js +++ b/.jsduck/external.js @@ -12,13 +12,6 @@ */ /** - * @class TextNode - * @extends CharacterData - * - * A text node. [See the DOM specification for more](http://www.w3.org/TR/dom/#text). - */ - -/** * @class CommentNode * @extends CharacterData * @@ -26,10 +19,24 @@ */ /** + * @class Document + * @extends Node + * + * A DOM Document. [See the DOM specification for more](http://www.w3.org/TR/dom/#document). + */ + +/** * @class Element * @extends Node * * An HTML element. [See the DOM specification for more](http://www.w3.org/TR/dom/#element). + */ + +/** + * @class TextNode + * @extends CharacterData + * + * A text node. [See the DOM specification for more](http://www.w3.org/TR/dom/#text). */ /** @@ -49,3 +56,19 @@ * * A Request object for the express application. [See the express documentation for more](http://expressjs.com/api.html#req.params). */ + +/** + * @class Map + * + * The Map object is a simple key/value map. Any value (both objects + * and primitive values) may be used as either a key or a value. + * [See MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map). + */ + +/** + * @class Set + * + * The Set object lets you store unique values of any type, whether + * primitive values or object references. + * [See MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set). + */ diff --git a/.jsduck/guides.json b/.jsduck/guides.json new file mode 100644 index 0000000..964fcd2 --- /dev/null +++ b/.jsduck/guides.json @@ -0,0 +1,31 @@ +[ + { + "title": "Parsoid guides", + "items": [ + { + "name": "setup", + "url": "../guides/setup", + "title": "Setting up Parsoid", + "description": "Get Parsoid set up on your machine and start using it." + }, + { + "name": "devsetup", + "url": "../guides/devsetup", + "title": "Setting up Parsoid for development", + "description": "Get Parsoid set up and start developing for it." + }, + { + "name": "apiuse", + "url": "../guides/apiuse", + "title": "Using Parsoid's HTTP API", + "description": "How to use Parsoid's HTTP API to parse and roundtrip wikitext." + }, + { + "name": "jsapi", + "url": "../guides/jsapi", + "title": "Using Parsoid's JavaScript API", + "description": "How to use Parsoid's JavaScript API to parse and manipulate article content." + } + ] + } +] diff --git a/api/ParsoidService.js b/api/ParsoidService.js index 54f78f3..c7328fe 100644 --- a/api/ParsoidService.js +++ b/api/ParsoidService.js @@ -1,4 +1,4 @@ -/** +/* * Simple Parsoid web service. */ 'use strict'; @@ -14,6 +14,12 @@ var util = require('util'); var uuid = require('node-uuid').v4; +/** + * @class + * @constructor + * @param {ParsoidConfig} parsoidConfig + * @param {Logger} processLogger + */ function ParsoidService(parsoidConfig, processLogger) { processLogger.log("info", "loading ..."); diff --git a/doc.guides.json b/doc.guides.json deleted file mode 100644 index 135b148..0000000 --- a/doc.guides.json +++ /dev/null @@ -1,25 +0,0 @@ -[ - { - "title": "Parsoid guides", - "items": [ - { - "name": "setup", - "url": "guides/setup", - "title": "Setting up Parsoid", - "description": "Get Parsoid set up on your machine and start using it." - }, - { - "name": "devsetup", - "url": "guides/devsetup", - "title": "Setting up Parsoid for development", - "description": "Get Parsoid set up and start developing for it." - }, - { - "name": "apiuse", - "url": "guides/apiuse", - "title": "Using Parsoid's API", - "description": "How to use Parsoid's HTTP API to parse and roundtrip wikitext." - } - ] - } -] diff --git a/guides/apiuse/README.md b/guides/apiuse/README.md index b149670..81910dd 100644 --- a/guides/apiuse/README.md +++ b/guides/apiuse/README.md @@ -4,12 +4,15 @@ you would much prefer it to be an HTML DOM, then Parsoid can best help you through its HTTP API that serves HTML (or JSON) responses. -## /{wiki prefix}/{article name} +This guide may become out of date; the latest information should be +available [on the wiki](https://www.mediawiki.org/wiki/Parsoid/API). + +## /v2/{wiki domain}/{html|pagebundle}/{article name}[/{revision}] ### GET If you make a GET request to the API, to a URI that represents a valid -interwiki prefix and an article name, you will get back an HTML document with +wikimedia domain and an article name, you will get back an HTML document with a bunch of extra information used for round-tripping. You can use this to do basic parsing of existing wiki pages. @@ -47,9 +50,9 @@ ### GET -Yield JSON object of the daemon name and version from package.json. If running -from a git repository, it would add the sha of the HEAD commit (git rev-parse -HEAD). Example: +Yields a JSON object of the daemon name and version from `package.json`. +If running from a git repository, it would add the sha of the HEAD commit +(`git rev-parse HEAD`). Example: $ curl http://localhost:8000/_version {"name":"mediawiki-parsoid","version":"0.0.1","sha":"63a778a1ffc1e9bd0dbb3a7571fe40bfb0a6d699"} diff --git a/guides/devsetup/README.md b/guides/devsetup/README.md index baab194..11d530e 100644 --- a/guides/devsetup/README.md +++ b/guides/devsetup/README.md @@ -9,21 +9,6 @@ Setup for developing Parsoid is, thankfully, brief. -### Getting test suite - -We use MediaWiki's core parser test suite rather than writing our own. This -sets a very high bar for our success, but it also means that we can ensure -totally correct behavior if the tests are passing. - -To fetch the test suite, go to the `tests/` directory and run this: - -``` -$ node fetch-parserTests.txt.js -``` - -This should pull the current parser tests to the tests directory. You may want -to run this command from time to time to make sure the tests are up to date. - ### Getting a Gerrit account and setting it up in Parsoid's repository If you want to submit patches to our project - and we highly suggest that you @@ -63,33 +48,59 @@ * tests/roundtrip-test.js * api/server.js +Luckily, you can test all of these with one command! +From the Parsoid base directory, run: + +``` +$ npm test +``` + +This will run all of the above tests, and some code style checkers as well. + +For more details on the different tests which are run, keep reading... + ### parserTests.js -To run the parser tests, go to the `tests/` directory, and run: +To run the parser tests, run: ``` -$ ./runtests.sh +$ node tests/parserTests ``` -This script is there to help remember the test modes and options we use, and -to assist in telling what tests change after a commit. If you want to know -about test changes in your commit, you should also run +This is quite noisy! You may wish to use the `--quiet` option, which +cuts down on the output from tests which are not failing. There are +quite a number of options to the parser test suite, but they are +pretty well documented if you run: ``` -$ ./runtests.sh -c +$ node tests/parserTests --help ``` -in this directory before you start working - it will commit the changes to a -git repository in `tests/results/` that will then be used to diff the test -results from the next test run. +To get you oriented: there are five possible modes which a given test +can be run in, corresponding to the command-line options `--wt2html`, +`--html2wt`, `--wt2wt`, `--html2html`, and `--selser`. If you don't +specify a mode on the command-line, it will run all of the tests +except for `--selser`. If you are trying to track down a bug, it's +often helpful to concentrate on `--wt2html` or `--html2wt` first, +before enabling the other modes. -If you prefer to run the parser tests on your own, something like +We inherited the parser test suite from the PHP parser, and still +regularly sync it with the copy in `mediawiki/core`. Unfortunately, +that means that we inherited a large number of tests which are not +appropriate for Parsoid, and which therefore fail. There are also +some real bugs which cause failing tests as well, of course! +In order to track regressions, we maintain a blacklist of +currently-failing tests in `tests/parserTests-blacklist.js`. +If you need to add or remove tests from the blacklist, then this +command will help: ``` -$ node parserTests --help +$ node tests/parserTests --rewrite-blacklist ``` -should tell you all you need to choose the right options. +We also gladly accept patches that mark tests as PHP-only (usually +with the `!! html/php` tag) when they've been audited to be irrelevant +for Parsoid. ### parse.js @@ -98,12 +109,12 @@ need to make sure it runs properly after your changes. Run something like ``` -$ echo "''Non'''-trivial'' wikitext''' [[with links]] {{echo|and templates}} | node parse --wt2wt +$ echo "''Non'''-trivial'' wikitext''' [[with links]] {{echo|and templates}} | node tests/parse --wt2wt ``` -from the `tests/` directory. That command should test a sufficient number -of the parser's - and serializer's - features that we can be confident in a -positive result. +That command should exercise a reasonable number of parser and +serializer features --- although not as many as the full `parserTests` +suite of course. ### roundtrip-test.js @@ -112,7 +123,7 @@ English Wikipedia which should be sufficient. Running ``` -$ node roundtrip-test.js "Barack Obama" +$ node tests/roundtrip-test.js "Barack Obama" ``` is a simple and stereotypical test case. If the script runs without issue, @@ -124,9 +135,10 @@ server - see the [setup instructions](#!/guide/setup) for how to do so - and load a page in your browser to make sure the API still responds accurately to responses. Loading -[French Wikipedia's page on Obama](http://localhost:8000/_rt/fr/Barack_Obama) +[French Wikipedia's page on Obama](http://localhost:8000/_rt/frwiki/Barack_Obama) is a pretty good test, so if that page loads completely, and there are no -errors in the server's output, then you can probably call this test passed. +semantic differences in the server's output, then you can probably +call this test passed. ## Submitting changes @@ -142,3 +154,4 @@ After you submit the patch, the Parsoid team will likely get around to reviewing it within a day or two, depending on their schedules. +You can also poke us on IRC (see above) to remind us to take a look. diff --git a/guides/setup/README.md b/guides/setup/README.md index 52a4c24..7413975 100644 --- a/guides/setup/README.md +++ b/guides/setup/README.md @@ -4,10 +4,6 @@ wikitext that produces HTML DOMs which can then be turned back into wikitext, even after modifications. -If you just want to turn wikitext into HTML, and don't need to round-trip back -into wikitext, you may be better off with another project, but Parsoid will -probably do what you want. - ## Prerequisites You'll need: @@ -42,15 +38,15 @@ ## Running the API The API is the main reason you might want to run Parsoid, because VisualEditor -uses it to do a lot of backend work. To run the API in a terminal, go to the -`api/` directory in the Parsoid repository and run the following: +uses it to do a lot of backend work. To run the API in a terminal, +from the base directory in the Parsoid repository run the following: ``` -$ node server +$ node api/server ``` -There is also, in the `api/` directory, a nice runserver.sh script that will -perhaps be useful to someone running the API as a more permanent service. The +There is also, in the `api/` directory, a nice `runserver.sh` script that +might be useful to someone running the API as a more permanent service. The script was originally written for Wikimedia's internal purposes, but it could be useful anywhere if it was tweaked a little bit. @@ -61,19 +57,24 @@ ## Running the basic parse tool If you aren't looking to run an API service, or VisualEditor, or if you just -want to test Parsoid's capabilities, you can use our simple parse.js script. -This time, go to the `tests/` directory in the Parsoid repository and do +want to test Parsoid's capabilities, you can use our simple `parse.js` script. +Again, from the base directory in the Parsoid repository, run something like: ``` -$ echo "some harmless [[wikitext]]" | node parse +$ echo "some harmless [[wikitext]]" | node tests/parse ``` This will run the echoed text through the wikitext parser and show you the resulting HTML. You can also specify different options for different output - `--wt2wt` will convert wikitext to HTML and then back to wikitext, `--html2wt` will convert HTML to wikitext, and `--html2html` will convert HTML to wikitext -and then back to HTML. You can test the parser this way - please use this tool +and then back to HTML. By default the HTML output will contain a lot +of internal Parsoid data (`data-parsoid` attributes, for example). +You may wish to use the command-line option `--normalize=parsoid` to +clean things up a bit and make it easier to tell what's going on. + +You can test the parser this way --- please use this tool when trying to report bugs. ## More setup and usage examples diff --git a/jsduck-conf.json b/jsduck-conf.json deleted file mode 100644 index f5c17a5..0000000 --- a/jsduck-conf.json +++ /dev/null @@ -1,33 +0,0 @@ -{ - "--title": "Parsoid documentation", - "--warnings": [ "-no_doc" ], - "--ignore-global": true, - "--builtin-classes": true, - "--output": "doc/", - "--guides": "./doc.guides.json", - "--": [ - "./doc.basicTypes.js", - "./lib/core-upgrade.js", - "./lib/ext.core.AttributeExpander.js", - "./lib/ext.core.BehaviorSwitchHandler.js", - "./lib/ext.core.LinkHandler.js", - "./lib/ext.core.ParserFunctions.js", - "./lib/ext.core.Sanitizer.js", - "./lib/ext.util.TokenCollector.js", - "./lib/mediawiki.ApiRequest.js", - "./lib/mediawiki.DOMUtils.js", - "./lib/mediawiki.ParsoidConfig.js", - "./lib/mediawiki.SelectiveSerializer.js", - "./lib/mediawiki.Title.js", - "./lib/mediawiki.TokenTransformManager.js", - "./lib/mediawiki.Util.js", - "./lib/mediawiki.WikiConfig.js", - "./lib/mediawiki.parser.defines.js", - "./lib/mediawiki.parser.environment.js", - "./api/ParserService.js", - "./tests/parserTests.js", - "./tests/parse.js", - "./tests/roundtrip-test.js" - ] -} - diff --git a/jsduck.json b/jsduck.json new file mode 100644 index 0000000..92cccda --- /dev/null +++ b/jsduck.json @@ -0,0 +1,28 @@ +{ + "--title": "Parsoid - Documentation", + "--output": "docs", + "--categories": ".jsduck/categories.json", + "--tags": ".jsduck/CustomTags.rb", + "--processes": "0", + "--warnings-exit-nonzero": true, + "--ignore-global": true, + "--builtin-classes": true, + "--warnings": [ "-nodoc(class,public)" ], + "--guides": ".jsduck/guides.json", + "--": [ + ".jsduck/external.js", + "lib/index.js", + "lib/jsapi.js", + "lib/LogData.js", + "lib/Logger.js", + "lib/ParsoidLogger.js", + "lib/mediawiki.DOMUtils.js", + "lib/mediawiki.ParsoidConfig.js", + "lib/mediawiki.Title.js", + "lib/mediawiki.Util.js", + "lib/mediawiki.WikiConfig.js", + "lib/mediawiki.parser.defines.js", + "lib/mediawiki.parser.environment.js", + "api/ParsoidService.js" + ] +} diff --git a/lib/LogData.js b/lib/LogData.js index fc88176..1553d11 100644 --- a/lib/LogData.js +++ b/lib/LogData.js @@ -11,8 +11,8 @@ * * @class * @constructor - * @param {string} logType Type of log being generated. - * @param {object} logObject Data being logged. + * @param {String} logType Type of log being generated. + * @param {Object} logObject Data being logged. */ var LogData = function(logType, logObject) { this.logType = logType; diff --git a/lib/Logger.js b/lib/Logger.js index 88dcd22..658662c 100644 --- a/lib/Logger.js +++ b/lib/Logger.js @@ -13,7 +13,7 @@ * * @class * @constructor - * @param {boolean} dontRegisterDefaultBackend + * @param {Object} [opts] */ var Logger = function(opts) { if (!opts) { opts = {}; } diff --git a/lib/ParsoidLogger.js b/lib/ParsoidLogger.js index 715ce29..5207f0a 100644 --- a/lib/ParsoidLogger.js +++ b/lib/ParsoidLogger.js @@ -28,6 +28,12 @@ coreutil.inherits(ParsoidLogData, LogData); +/** + * @class + * @extends Logger + * @constructor + * @param {MWParserEnvironment} env + */ function ParsoidLogger(env) { this.env = env; Logger.apply(this, {}); diff --git a/lib/jsapi.js b/lib/jsapi.js index d1524e0..ece9e90 100644 --- a/lib/jsapi.js +++ b/lib/jsapi.js @@ -1,4 +1,4 @@ -/** +/* * Handy JavaScript API for Parsoid DOM, inspired by the * python `mwparserfromhell` package. */ diff --git a/lib/mediawiki.DOMUtils.js b/lib/mediawiki.DOMUtils.js index 3da1f91..306057b 100644 --- a/lib/mediawiki.DOMUtils.js +++ b/lib/mediawiki.DOMUtils.js @@ -1,4 +1,4 @@ -/** +/* * General DOM utilities. */ 'use strict'; @@ -20,7 +20,7 @@ /** - * @class + * @class DOMUtils * @singleton * General DOM utilities */ @@ -86,8 +86,8 @@ /** * Is 'node' a block node that is also visible in wikitext? - * An example of an invisible block node is a <p>-tag that - * Parsoid generated, or a <ul>, <ol> tag. + * An example of an invisible block node is a `<p>`-tag that + * Parsoid generated, or a `<ul>`, `<ol>` tag. * * @param {Node} node */ @@ -137,8 +137,8 @@ * Attribute equality test * @param {Node} nodeA * @param {Node} nodeB - * @param {ignoreableAttribs} Set of attributes that should be ignored - * @param {specializedAttribHandlers} Map of attributes with specialized equals handlers + * @param {Set} [ignoreableAttribs] Set of attributes that should be ignored + * @param {Map} [specializedAttribHandlers] Map of attributes with specialized equals handlers */ attribsEquals: function(nodeA, nodeB, ignoreableAttribs, specializedAttribHandlers) { if (!ignoreableAttribs) { @@ -363,7 +363,7 @@ /** * Get an object from a JSON-encoded XML attribute on a node. * - * @param {string} name Name of the attribute + * @param {String} name Name of the attribute * @param {Mixed} defaultVal What should be returned if we fail to find a valid JSON structure */ getJSONAttribute: function(node, name, defaultVal) { @@ -1772,42 +1772,43 @@ * of the HTML DOM for the purposes of additional token transformations * that will be applied to them. * - * @param {Object} env + * @param {MWParserEnvironment} env * The active environment/context. * - * @param {Object} token + * @param {Token} token * The token that generated the DOM. * * @param {Object} expansion - * expansion.html -- HTML of the expansion - * expansion.nodes -- outermost nodes of the HTML + * @param {String} expansion.html + * HTML of the expansion + * @param {Node[]} expansion.nodes + * Outermost nodes of the HTML * - * @param {Object} addAttrsCB + * @param {Function} addAttrsCB * Callback that adds additional attributes to the generated tokens. * - * @param {Object} opts - * aboutId : The about-id to set on the generated tokens. - * - * noAboutId : If true, an about-id will not be added to the tokens - * if an aboutId is not provided. - * Ex: <figure> - * - * tsr : The TSR to set on the generated tokens. This TSR is - * used to compute DSR on the placeholder tokens. - * The computed DSR is transferred over to the unpacked DOM - * if setDSR is true (see below). - * - * setDSR : When the DOM-fragment is unpacked, this option governs - * whether the DSR from the placeholder node is transferred - * over to the unpacked DOM or not. - * Ex: Cite, reused transclusions - * - * isForeignContent : - * Does the DOM come from outside the main page? This governs - * how the encapsulation ids are assigned to the unpacked DOM. - * Ex: transclusions, extensions -- all siblings get the same - * about id. This is not true for <figure> HTML. - * + * @param {Object} [opts] + * @param {String} opts.aboutId + * The about-id to set on the generated tokens. + * @param {Boolean} opts.noAboutId + * If true, an about-id will not be added to the tokens + * if an aboutId is not provided. + * For example: `<figure>` + * @param {Object} opts.tsr + * The TSR to set on the generated tokens. This TSR is + * used to compute DSR on the placeholder tokens. + * The computed DSR is transferred over to the unpacked DOM + * if setDSR is true (see below). + * @param {Boolean} opts.setDSR + * When the DOM fragment is unpacked, this option governs + * whether the DSR from the placeholder node is transferred + * over to the unpacked DOM or not. + * For example: Cite, reused transclusions + * @param {Boolean} opts.isForeignContent + * Does the DOM come from outside the main page? This governs + * how the encapsulation ids are assigned to the unpacked DOM. + * For example: transclusions, extensions -- all siblings get the same + * about id. This is not true for `<figure>` HTML. */ encapsulateExpansionHTML: function(env, token, expansion, opts) { opts = opts || {}; @@ -1870,16 +1871,16 @@ * The DOMPostProcessor will unpack the fragment and insert the HTML * back into the DOM. * - * @param {Object} env + * @param {MWParserEnvironment} env * The active environment/context. * - * @param {Object} token + * @param {Token} token * The token that generated the DOM. * - * @param {Object} docOrHTML + * @param {Node|String} docOrHTML * The DOM (or HTML string) that the token expanded to. * - * @param {Object} addAttrsCB + * @param {Function} addAttrsCB * Callback that adds additional attributes to the generated tokens. * * @param {Object} opts @@ -1919,6 +1920,8 @@ * Compute, when possible, the wikitext source for a node in * an environment env. Returns null if the source cannot be * extracted. + * @param {MWParserEnvironment} env + * @param {Node} node */ getWTSource: function(env, node) { var data = this.getDataParsoid(node); @@ -1927,6 +1930,9 @@ env.page.src.substring(dsr[0], dsr[1]) : null; }, + /** + * @param {Node} node + */ deleteNode: function(node) { if (node.parentNode) { node.parentNode.removeChild(node); @@ -2205,8 +2211,11 @@ * preserved/inserted around the same set of tags that formatHTML would * add them in front of. * - * @param source {document} - * @return {document} + * @param {Node} body + * The document `<body>` node to normalize. + * @param {RegExp} [stripSpanTypeof] + * @param {Boolean} [parsoidOnly=false] + * @return {Node} */ DOMUtils.normalizeIEW = function(body, stripSpanTypeof, parsoidOnly) { var newlineAround = function(node) { @@ -2374,9 +2383,9 @@ * markup through (like property and typeof attributes), for better * checking of parsoid-only test cases. * - * @param {string} out - * @param {bool} parsoidOnly - * @returns {string} + * @param {String} out + * @param {Boolean} [parsoidOnly=false] + * @returns {String} */ DOMUtils.normalizeOut = function(out, parsoidOnly) { if (typeof (out) === 'string') { @@ -2468,7 +2477,7 @@ * * Parse HTML, return the tree. * - * @param {string} html + * @param {String} html * @returns {Node} */ DOMUtils.parseHTML = function(html) { @@ -2484,7 +2493,7 @@ /** * Merge a text node with text node siblings * - * @param {object} Node + * @param {Node} node */ DOMUtils.mergeSiblingTextNodes = function(node) { var otherNode = node.previousSibling; diff --git a/lib/mediawiki.ParsoidConfig.js b/lib/mediawiki.ParsoidConfig.js index 5f47425..e8a150c 100644 --- a/lib/mediawiki.ParsoidConfig.js +++ b/lib/mediawiki.ParsoidConfig.js @@ -11,8 +11,9 @@ var JSUtils = require('./jsutils.js').JSUtils; var sitematrix = require('./sitematrix.json').sitematrix; -/** - * @property {Object} Timeout values for various things. All values in ms. +/* + * @property {Object} CONFIG_DEFAULTS + * Timeout values for various things. All values in ms. */ var CONFIG_DEFAULTS = Object.freeze({ timeouts: { @@ -226,19 +227,21 @@ ParsoidConfig.prototype.linting = false; /** - * @property {URL} linterAPI + * @property {String|null} linterAPI * The URL for LintBridge API endpoint */ ParsoidConfig.prototype.linterAPI = null; /** - * @property {Function} the logger output function + * @property {Function} loggerBackend + * The logger output function. * By default, use stderr to output logs. */ ParsoidConfig.prototype.loggerBackend = null; /** - * @property {Function} the tracer output function + * @property {Function} tracerBackend + * The tracer output function. * By default, use stderr to output traces. */ ParsoidConfig.prototype.tracerBackend = null; @@ -365,13 +368,14 @@ * * Set an mw api prefix. * - * @param {string} prefix - * @param {string|object} If a string, apiConf is the apiURI. - * @param {string} apiConf.uri The URL to the wiki's api.php. - * @param {string} apiConf.proxy.uri The URL of a proxy to use for API requests, + * @param {String} prefix + * @param {String|Object} apiConf If a string, apiConf is the apiURI. + * @param {String} apiConf.uri The URL to the wiki's api.php. + * @param {Object} apiConf.proxy + * @param {String} apiConf.proxy.uri The URL of a proxy to use for API requests, * or null to explicitly disable API request proxying for this wiki. Will fall * back to ParsoidConfig.defaultAPIProxyURI if undefined (default value). - * @param {object} apiConf.proxy.headers Headers to add when proxying. + * @param {Object} apiConf.proxy.headers Headers to add when proxying. */ ParsoidConfig.prototype.setInterwiki = // Alias for backwards compat. ParsoidConfig.prototype.setMwApi = function(prefix, apiConf) { diff --git a/lib/mediawiki.Title.js b/lib/mediawiki.Title.js index 6db41b1..cce2569 100644 --- a/lib/mediawiki.Title.js +++ b/lib/mediawiki.Title.js @@ -108,7 +108,7 @@ /** * @class * - * Represents a namespace, meant for use in the #Title class. + * Represents a namespace, meant for use in the {@link Title} class. * * @constructor * @param {number} id The id of the namespace to represent. diff --git a/lib/mediawiki.Util.js b/lib/mediawiki.Util.js index 860edf7..6b662e9 100644 --- a/lib/mediawiki.Util.js +++ b/lib/mediawiki.Util.js @@ -1,4 +1,4 @@ -/** +/* * This file contains general utilities for token transforms. */ /* jshint nonstandard:true */ // define 'unescape' @@ -245,8 +245,11 @@ * * Set the color flags, based on an options object. * - * @param {Options} options The options object to use for setting - * the mode of the 'color' package. + * @param {Object} options + * The options object to use for setting the mode of the 'color' package. + * @param {String|Boolean} options.color + * Whether to use color. Passing 'auto' will enable color only if + * stdout is a TTY device. */ setColorFlags: function(options) { var colors = require('colors'); @@ -986,11 +989,16 @@ * be a bit fragile and makes dom-fragments a leaky abstraction by leaking subpipeline * processing into the top-level pipeline. * - * @param {Token[]} content The array of tokens to process - * @param {int[]} srcOffsets Wikitext source offsets (start/end) of these tokens - * @param {Object} opts Parsing options (optional) - * opts.contextTok: The token that generated the content - * opts.noPre: Suppress indent-pres in content + * @param {Token[]} content + * The array of tokens to process + * @param {Number[]} srcOffsets + * Wikitext source offsets (start/end) of these tokens + * @param {Object} [opts] + * Parsing options + * @param {Token} opts.contextTok + * The token that generated the content + * @param {Boolean} opts.noPre + * Suppress indent-pres in content */ getDOMFragmentToken: function(content, srcOffsets, opts) { if (!opts) { @@ -1429,9 +1437,12 @@ * Perform a HTTP request using the 'request' package, and retry on failures * * Only use on idempotent HTTP end points - * @param {number} retries -- the number of retries to attempt - * @param {object} paramOptions -- request options - * @param {function} cb -- request cb: function(error, response, body) + * @param {Number} retries The number of retries to attempt. + * @param {Object} requestOptions Request options. + * @param {Function} cb Request callback. + * @param {Error} cb.error + * @param {Object} cb.response + * @param {Object} cb.body */ Util.retryingHTTPRequest = function(retries, requestOptions, cb) { var delay = 100; // start with 100ms diff --git a/lib/mediawiki.WikiConfig.js b/lib/mediawiki.WikiConfig.js index a79ba04..f1d03bd 100644 --- a/lib/mediawiki.WikiConfig.js +++ b/lib/mediawiki.WikiConfig.js @@ -645,6 +645,8 @@ * Matcher for RFC/PMID URL patterns, returning the type and number. The match * method takes a string and returns false on no match or a tuple like this on match: * ['RFC', '12345'] + * @property {Object} ExtResourceURLPatternMatcher + * @property {Function} ExtResourceURLPatternMatcher.match */ WikiConfig.prototype.ExtResourceURLPatternMatcher = (function() { var keys = Object.keys(WikiConfig.prototype.ExtResourceURLPatterns); @@ -679,10 +681,7 @@ })(); /** - * Matcher for interwiki prefixes. - */ - -/** + * Matcher for valid protocols, must be anchored at start of string. * @param {string} potentialLink */ WikiConfig.prototype.hasValidProtocol = function(potentialLink) { @@ -695,6 +694,7 @@ }; /** + * Matcher for valid protocols, may occur at any point within string. * @param {string} potentialLink */ WikiConfig.prototype.findValidProtocol = function(potentialLink) { diff --git a/lib/mediawiki.parser.defines.js b/lib/mediawiki.parser.defines.js index 6d370cc..8452fe2 100644 --- a/lib/mediawiki.parser.defines.js +++ b/lib/mediawiki.parser.defines.js @@ -1,11 +1,6 @@ 'use strict'; require('./core-upgrade.js'); -/** - * @class ParserDefinesModule - * @singleton - */ - var async = require('async'); var Util; // Util module var for circular dependency avoidance var requireUtil = function() { diff --git a/lib/mediawiki.parser.environment.js b/lib/mediawiki.parser.environment.js index 78fcd4c..cb98592 100644 --- a/lib/mediawiki.parser.environment.js +++ b/lib/mediawiki.parser.environment.js @@ -19,8 +19,8 @@ * a page object that represents the page we're parsing, and more. * * @constructor - * @param {ParsoidConfig/null} parsoidConfig - * @param {WikiConfig/null} wikiConfig + * @param {ParsoidConfig|null} parsoidConfig + * @param {WikiConfig|null} wikiConfig */ var MWParserEnvironment = function(parsoidConfig, wikiConfig, options) { options = options || {}; @@ -112,45 +112,44 @@ /** * @property {Object} page - * @property {string} page.name - * @property {String/null} page.src - * @property {Node/null} page.dom - * @property {string} page.relativeLinkPrefix - * Any leading ..?/ strings that will be necessary for building links. - * @property {Number/null} page.id - * The revision ID we want to use for the page. + * @property {String} page.name + * @property {String|null} page.src + * @property {Node|null} page.dom + * @property {String} page.relativeLinkPrefix + * Any leading ..?/ strings that will be necessary for building links. + * @property {Number|null} page.id + * The revision ID we want to use for the page. */ + /** * @method * * Set the src and optionally meta information for the page we're parsing. * * If the argument is a simple string, will clear metadata and just - * set this.page.src. Otherwise, the provided metadata object should + * set `this.page.src`. Otherwise, the provided metadata object should * have fields corresponding to the JSON output given by * action=query&prop=revisions on the MW API. That is: - * <pre> - * metadata = { - * title: // normalized title (ie, spaces not underscores) - * ns: // namespace - * id: // page id - * revision: { - * revid: // revision id - * parentid: // revision parent - * timestamp: - * user: // contributor username - * userid: // contributor user id - * sha1: - * size: // in bytes - * comment: - * contentmodel: - * contentformat: - * "*": // actual source text --> copied to this.page.src - * } - * } - * </pre> * - * @param {String or Object} page source or metadata + * metadata = { + * title: // normalized title (ie, spaces not underscores) + * ns: // namespace + * id: // page id + * revision: { + * revid: // revision id + * parentid: // revision parent + * timestamp: + * user: // contributor username + * userid: // contributor user id + * sha1: + * size: // in bytes + * comment: + * contentmodel: + * contentformat: + * "* ": // actual source text --> copied to this.page.src + * } + * } + * @param {String|Object} page source or metadata */ MWParserEnvironment.prototype.setPageSrcInfo = function(srcOrMetadata) { if (typeof (srcOrMetadata) === 'string' || srcOrMetadata === null) { @@ -232,8 +231,8 @@ * * Alternate constructor for MWParserEnvironments * - * @param {ParsoidConfig/null} parsoidConfig - * @param {WikiConfig/null} wikiConfig + * @param {ParsoidConfig|null} parsoidConfig + * @param {WikiConfig|null} wikiConfig * @param {Object} options * @param {Function} cb * @param {Error} cb.err diff --git a/package.json b/package.json index bb79447..ba4047d 100644 --- a/package.json +++ b/package.json @@ -50,7 +50,8 @@ "cover-mocha": "istanbul cover _mocha --dir ./coverage/mocha -- --opts tests/mocha/mocha.opts tests/mocha", "cover-parserTests": "istanbul cover tests/parserTests.js --dir ./coverage/parserTests -- --wt2html --wt2wt --html2wt --html2html --selser --no-color --quiet --blacklist", "coverage": "npm run cover-mocha && npm run cover-parserTests && istanbul report", - "coveralls": "cat ./coverage/lcov.info | coveralls && rm -rf ./coverage" + "coveralls": "cat ./coverage/lcov.info | coveralls && rm -rf ./coverage", + "doc": "jsduck --config jsduck.json" }, "repository": { "type": "git", diff --git a/docs/specs/apiv2.yaml b/specs/apiv2.yaml similarity index 100% rename from docs/specs/apiv2.yaml rename to specs/apiv2.yaml -- To view, visit https://gerrit.wikimedia.org/r/227580 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: merged Gerrit-Change-Id: I37f761543e4c32c23261bf8ad1302539bebacb3b Gerrit-PatchSet: 6 Gerrit-Project: mediawiki/services/parsoid Gerrit-Branch: master Gerrit-Owner: Cscott <[email protected]> Gerrit-Reviewer: Arlolra <[email protected]> Gerrit-Reviewer: Cscott <[email protected]> Gerrit-Reviewer: Subramanya Sastry <[email protected]> Gerrit-Reviewer: jenkins-bot <> _______________________________________________ MediaWiki-commits mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
