diff --git a/.jsdoc.json b/.jsdoc.json new file mode 100644 index 000000000..cb5577d72 --- /dev/null +++ b/.jsdoc.json @@ -0,0 +1,91 @@ +{ + "opts": { + "encoding": "utf8", + "destination": "docs", + "package": "package.json", + "readme": "README.md", + "pedantic": false, + "private": true, + "recurse": true, + "template": "node_modules/jsdoc-wmf-theme", + "class-hierarchy": { + "showList": true + } + }, + "plugins": [ + "plugins/markdown", + "plugins/summarize", + "node_modules/jsdoc-class-hierarchy" + ], + "source": { + "include": [ "src", "rebaser/src" ] + }, + "templates": { + "cleverLinks": true, + "default": { + "useLongnameInNav": true + }, + "wmf": { + "maintitle": "VisualEditor", + "repository": "https://gerrit.wikimedia.org/g/VisualEditor/VisualEditor/", + "linkMap": { + "Mixed": "#", + + "Array": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array", + "Error": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error", + "Object": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object", + "Promise": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise", + + "Blob": "https://developer.mozilla.org/en-US/docs/Web/API/Blob", + "DataTransfer": "https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer", + "DataTransferItem": "https://developer.mozilla.org/en-US/docs/Web/API/DataTransferItem", + "Event": "https://developer.mozilla.org/en-US/docs/Web/API/Event", + "HTMLDocument": "https://developer.mozilla.org/en-US/docs/Web/API/HTMLDocument", + "HTMLElement": "https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement", + "MutationRecord": "https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord", + "Node": "https://developer.mozilla.org/en-US/docs/Web/API/Node", + "NodeList": "https://developer.mozilla.org/en-US/docs/Web/API/NodeList", + "Range": "https://developer.mozilla.org/en-US/docs/Web/API/Range", + "Selection": "https://developer.mozilla.org/en-US/docs/Web/API/Selection", + + "jQuery": "http://api.jquery.com/", + "jQuery.Deferred": "http://api.jquery.com/jQuery.Deferred/", + "jQuery.Event": "http://api.jquery.com/Types/#Event", + "jQuery.Promise": "http://api.jquery.com/Types/#Promise", + + "OO.EventEmitter": "https://doc.wikimedia.org/oojs/master/OO.EventEmitter.html", + "OO.Factory": "https://doc.wikimedia.org/oojs/master/OO.Factory.html", + "OO.Registry": "https://doc.wikimedia.org/oojs/master/OO.Registry.html", + + "OO.ui.mixin.GroupElement": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.mixin.GroupElement.html", + "OO.ui.mixin.PendingElement": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.mixin.PendingElement.html", + "OO.ui.BookletLayout": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.BookletLayout.html", + "OO.ui.ButtonSelectWidget": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ButtonSelectWidget.html", + "OO.ui.DecoratedOptionWidget": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.DecoratedOptionWidget.html", + "OO.ui.Dialog": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.Dialog.html", + "OO.ui.Element": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.Element.html", + "OO.ui.HtmlSnippet": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.HtmlSnippet.html", + "OO.ui.MenuOptionWidget": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.MenuOptionWidget.html", + "OO.ui.MessageDialog": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.MessageDialog.html", + "OO.ui.MultilineTextInputWidget": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.MultilineTextInputWidget.html", + "OO.ui.NumberInputWidget": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.NumberInputWidget.html", + "OO.ui.OptionWidget": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.OptionWidget.html", + "OO.ui.PageLayout": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.PageLayout.html", + "OO.ui.PopupTool": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.PopupTool.html", + "OO.ui.Process": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.Process.html", + "OO.ui.ProcessDialog": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ProcessDialog.html", + "OO.ui.SearchWidget": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.SearchWidget.html", + "OO.ui.SelectWidget": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.SelectWidget.html", + "OO.ui.TextInputWidget": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.TextInputWidget.html", + "OO.ui.Tool": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.Tool.html", + "OO.ui.Toolbar": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.Toolbar.html", + "OO.ui.ToolFactory": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ToolFactory.html", + "OO.ui.ToolGroup": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ToolGroup.html", + "OO.ui.ToolGroupTool": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.ToolGroupTool.html", + "OO.ui.Widget": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.Widget.html", + "OO.ui.Window": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.Window.html", + "OO.ui.WindowManager": "https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.WindowManager.html" + } + } + } +} diff --git a/.jsduck/CustomTags.rb b/.jsduck/CustomTags.rb deleted file mode 100644 index b37eab06e..000000000 --- a/.jsduck/CustomTags.rb +++ /dev/null @@ -1,116 +0,0 @@ -# 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 -

Source

- #{source[:doc]} - EOHTML - end.join - 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] = '
  • ' + render_long_see(tag[:doc], formatter, position) + '
    • ' - end - end - - def to_html(context) - <<-EOHTML -

    Related

    - - 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 -

    Context

    - #{ 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 deleted file mode 100644 index 2b1f3d54e..000000000 --- a/.jsduck/categories.json +++ /dev/null @@ -1,343 +0,0 @@ -[ - { - "name": "General", - "groups": [ - { - "name": "Utilities", - "classes": [ - "ve", - "ve.Range", - "ve.PositionStep", - "ve.SelectionState", - "ve.EventSequencer", - "ve.Filibuster", - "ve.TriggerListener", - "ve.Scheduler" - ] - }, - { - "name": "Nodes", - "classes": ["ve.Node", "ve.BranchNode", "ve.LeafNode", "ve.Document"] - } - ] - }, - { - "name": "Initialization", - "groups": [ - { - "name": "General", - "classes": [ - "ve.init", - "ve.init.Platform", - "ve.init.Target", - "ve.init.*Storage", - "global" - ] - }, - { - "name": "Stand-alone", - "classes": ["ve.init.sa*"] - } - ] - }, - { - "name": "DataModel", - "groups": [ - { - "name": "General", - "classes": [ - "ve.dm", - "ve.dm.Model", - "ve.dm.ModelRegistry", - "ve.dm.ModelFactory", - "ve.dm.AnnotationFactory", - "ve.dm.NodeFactory", - "ve.dm.Converter", - "ve.dm.DataString", - "ve.dm.HashValueStore", - "ve.dm.Scalable", - "ve.dm.Surface", - "ve.dm.*SurfaceFragment", - "ve.dm.*Selection", - "ve.dm.Transaction", - "ve.dm.TransactionBuilder", - "ve.dm.TransactionSquasher", - "ve.dm.TreeCursor", - "ve.dm.TreeModifier", - "ve.dm.TransactionProcessor", - "ve.dm.TransactionProcessor.*" - ] - }, - { - "name": "Annotations", - "classes": ["ve.dm.*Annotation", "ve.dm.AnnotationSet"] - }, - { - "name": "Meta items", - "classes": ["ve.dm.*MetaItem", "ve.dm.MetaList"] - }, - { - "name": "Internal list", - "classes": ["ve.dm.InternalList"] - }, - { - "name": "Nodes and documents", - "classes": ["ve.dm.Document", "ve.dm.*Slice", "ve.dm.*Node"] - }, - { - "name": "Linear data", - "classes": ["ve.dm.*LinearData*"] - }, - { - "name": "Models", - "classes": ["ve.dm.*Model"] - }, - { - "name": "Table model", - "classes": [ - "ve.dm.TableMatrix", - "ve.dm.TableMatrixCell", - "ve.dm.TableNodeCellIterator" - ] - }, - { - "name": "Rebasing", - "classes": [ - "ve.dm.Change", - "ve.dm.RebaseClient", - "ve.dm.SurfaceSynchronizer" - ] - } - ] - }, - { - "name": "ContentEditable", - "groups": [ - { - "name": "General", - "classes": [ - "ve.ce", - "ve.ce.View", - "ve.ce.AnnotationFactory", - "ve.ce.NodeFactory", - "ve.ce.Surface", - "ve.ce.SurfaceObserver", - "ve.ce.*Selection", - "ve.ce.RangeState", - "ve.ce.TextState", - "ve.ce.TextStateChunk" - ] - }, - { - "name": "Annotations", - "classes": ["ve.ce.*Annotation"] - }, - { - "name": "Meta items", - "classes": ["ve.ce.MetaItem"] - }, - { - "name": "Factories", - "classes": ["ve.ce.*Factory"] - }, - { - "name": "Key down handlers", - "classes": ["ve.ce.*KeyDownHandler"] - }, - { - "name": "Nodes", - "classes": ["ve.ce.Document", "ve.ce.*Node"] - } - ] - }, - { - "name": "User Interface", - "groups": [ - { - "name": "General", - "classes": [ - "ve.ui", - "ve.ui.*Surface", - "ve.ui.*Context", - "ve.ui.Overlay", - "ve.ui.*Toolbar", - "ve.ui.DebugBar", - "ve.ui.Trigger", - "ve.ui.TabIndexScope" - ] - }, - { - "name": "Actions", - "classes": ["ve.ui.*Action"] - }, - { - "name": "Commands", - "classes": ["ve.ui.*Command"] - }, - { - "name": "Context items", - "classes": ["ve.ui.*ContextItem"] - }, - { - "name": "Data transfer handlers", - "classes": ["ve.ui.*TransferHandler", "ve.ui.DataTransferItem"] - }, - { - "name": "Elements", - "classes": ["ve.ui.*Element"] - }, - { - "name": "Factories", - "classes": ["ve.ui.*Factory"] - }, - { - "name": "Layouts", - "classes": ["ve.ui.*Layout"] - }, - { - "name": "Pages", - "classes": ["ve.ui.*Page"] - }, - { - "name": "Registries", - "classes": ["ve.ui.*Registry"] - }, - { - "name": "Sequences", - "classes": ["ve.ui.*Sequence"] - }, - { - "name": "Tools", - "classes": ["ve.ui.*Tool"] - }, - { - "name": "Widgets", - "classes": ["ve.ui.*Widget"] - }, - { - "name": "Windows", - "classes": [ - "ve.ui.*WindowManager", - "ve.ui.*Window", - "ve.ui.*Dialog", - "ve.ui.*Inspector" - ] - } - ] - }, - { - "name": "Diffing", - "groups": [ - { - "name": "Diffing", - "classes": [ - "ve.dm.VisualDiff", - "ve.DiffMatchPatch", - "ve.DiffTreeNode", - "ve.ui.DiffDialog", - "ve.ui.DiffElement" - ] - } - ] - }, - { - "name": "Upstream", - "groups": [ - { - "name": "OOjs", - "classes": [ - "OO", - "OO.EmitterList", - "OO.EventEmitter", - "OO.Factory", - "OO.Registry", - "OO.SortedEmitterList" - ] - }, - { - "name": "UnicodeJS", - "classes": [ - "unicodeJS", - "unicodeJS.TextString", - "unicodeJS.wordbreak", - "unicodeJS.graphemebreak", - "unicodeJS.characterclass" - ] - }, - { - "name": "OOjs UI General", - "classes": [ - "OO.ui", - "OO.ui.Element", - "OO.ui.HtmlSnippet", - "OO.ui.Toolbar", - "OO.ui.Window*", - "OO.ui.Dialog", - "OO.ui.Process", - "OO.ui.Error", - "OO.ui.ActionSet" - ] - }, - { - "name": "OOjs UI Mixins", - "classes": ["OO.ui.mixin", "OO.ui.mixin.*"] - }, - { - "name": "OOjs UI Factories", - "classes": ["OO.ui.*Factory"] - }, - { - "name": "OOjs UI Layouts", - "classes": ["OO.ui.*Layout"] - }, - { - "name": "OOjs UI Tool groups", - "classes": ["OO.ui.*ToolGroup"] - }, - { - "name": "OOjs UI Tools", - "classes": ["OO.ui.*Tool"] - }, - { - "name": "OOjs UI Widgets", - "classes": ["OO.ui.*Widget"] - }, - { - "name": "OOjs UI Dialogs", - "classes": ["OO.ui.*Dialog"] - }, - { - "name": "OOjs UI Themes", - "classes": ["OO.ui.*Theme"] - }, - { - "name": "jQuery", - "classes": ["jQuery", "jQuery.Event", "jQuery.Promise", "jQuery.Deferred", "jQuery.jqXHR", "QUnit"] - }, - { - "name": "treeDiffer", - "classes": ["treeDiffer.Differ", "treeDiffer.Tree", "treeDiffer.TreeNode"] - }, - { - "name": "DiffMatchPatch", - "classes": ["diff_match_patch"] - }, - { - "name": "JavaScript", - "classes": [ - "Array", - "Boolean", - "Date", - "Function", - "Map", - "MutationRecord", - "Number", - "Object", - "RegExp", - "Set", - "String" - ] - } - ] - } -] diff --git a/.jsduck/eg-iframe.html b/.jsduck/eg-iframe.html deleted file mode 100644 index 8748806fd..000000000 --- a/.jsduck/eg-iframe.html +++ /dev/null @@ -1,98 +0,0 @@ - - - - - VisualEditor Example - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/.jsduck/eg-iframe.html.template b/.jsduck/eg-iframe.html.template deleted file mode 100644 index 73d89281c..000000000 --- a/.jsduck/eg-iframe.html.template +++ /dev/null @@ -1,41 +0,0 @@ - - - - - VisualEditor Example - - - - - - - - - - - - - diff --git a/.jsduck/external-ooui.js b/.jsduck/external-ooui.js deleted file mode 100644 index 31d37eb7f..000000000 --- a/.jsduck/external-ooui.js +++ /dev/null @@ -1,569 +0,0 @@ -/** - * @class OO.ui - * @source - */ - -/** - * @class OO.ui.mixin - * @source - */ - -/** - * @class OO.ui.ActionFieldLayout - * @source - */ - -/** - * @class OO.ui.ActionSet - * @source - */ - -/** - * @class OO.ui.ActionWidget - * @source - */ - -/** - * @class OO.ui.ApexTheme - * @source - */ - -/** - * @class OO.ui.BarToolGroup - * @source - */ - -/** - * @class OO.ui.BlankTheme - * @source - */ - -/** - * @class OO.ui.BookletLayout - * @source - */ - -/** - * @class OO.ui.ButtonGroupWidget - * @source - */ - -/** - * @class OO.ui.ButtonInputWidget - * @source - */ - -/** - * @class OO.ui.ButtonMenuSelectWidget - * @source - */ - -/** - * @class OO.ui.ButtonOptionWidget - * @source - */ - -/** - * @class OO.ui.ButtonSelectWidget - * @source - */ - -/** - * @class OO.ui.ButtonWidget - * @source - */ - -/** - * @class OO.ui.CheckboxInputWidget - * @source - */ - -/** - * @class OO.ui.CheckboxMultioptionWidget - * @source - */ - -/** - * @class OO.ui.CheckboxMultiselectInputWidget - * @source - */ - -/** - * @class OO.ui.CheckboxMultiselectWidget - * @source - */ - -/** - * @class OO.ui.ComboBoxInputWidget - * @source - */ - -/** - * @class OO.ui.CopyTextLayout - * @source - */ - -/** - * @class OO.ui.DecoratedOptionWidget - * @source - */ - -/** - * @class OO.ui.Dialog - * @source - */ - -/** - * @class OO.ui.DropdownInputWidget - * @source - */ - -/** - * @class OO.ui.DropdownWidget - * @source - */ - -/** - * @class OO.ui.Element - * @source - */ - -/** - * @class OO.ui.Error - * @source - */ - -/** - * @class OO.ui.FieldLayout - * @source - */ - -/** - * @class OO.ui.FieldsetLayout - * @source - */ - -/** - * @class OO.ui.FormLayout - * @source - */ - -/** - * @class OO.ui.HiddenInputWidget - * @source - */ - -/** - * @class OO.ui.HorizontalLayout - * @source - */ - -/** - * @class OO.ui.HtmlSnippet - * @source - */ - -/** - * @class OO.ui.IconWidget - * @source - */ - -/** - * @class OO.ui.IndexLayout - * @source - */ - -/** - * @class OO.ui.IndicatorWidget - * @source - */ - -/** - * @class OO.ui.InputWidget - * @source - */ - -/** - * @class OO.ui.LabelWidget - * @source - */ - -/** - * @class OO.ui.Layout - * @source - */ - -/** - * @class OO.ui.ListToolGroup - * @source - */ - -/** - * @class OO.ui.MenuLayout - * @source - */ - -/** - * @class OO.ui.MenuOptionWidget - * @source - */ - -/** - * @class OO.ui.MenuSectionOptionWidget - * @source - */ - -/** - * @class OO.ui.MenuSelectWidget - * @source - */ - -/** - * @class OO.ui.MenuTagMultiselectWidget - * @source - */ - -/** - * @class OO.ui.MenuToolGroup - * @source - */ - -/** - * @class OO.ui.MessageDialog - * @source - */ - -/** - * @class OO.ui.MessageWidget - * @source - */ - -/** - * @class OO.ui.mixin.AccessKeyedElement - * @source - */ - -/** - * @class OO.ui.mixin.ButtonElement - * @source - */ - -/** - * @class OO.ui.mixin.ClippableElement - * @source - */ - -/** - * @class OO.ui.mixin.DraggableElement - * @source - */ - -/** - * @class OO.ui.mixin.DraggableGroupElement - * @source - */ - -/** - * @class OO.ui.mixin.FlaggedElement - * @source - */ - -/** - * @class OO.ui.mixin.FloatableElement - * @source - */ - -/** - * @class OO.ui.mixin.GroupElement - * @source - */ - -/** - * @class OO.ui.mixin.IconElement - * @source - */ - -/** - * @class OO.ui.mixin.IndicatorElement - * @source - */ - -/** - * @class OO.ui.mixin.LabelElement - * @source - */ - -/** - * @class OO.ui.mixin.LookupElement - * @source - */ - -/** - * @class OO.ui.mixin.PendingElement - * @source - */ - -/** - * @class OO.ui.mixin.PopupElement - * @source - */ - -/** - * @class OO.ui.mixin.RequestManager - * @source - */ - -/** - * @class OO.ui.mixin.RequiredElement - * @source - */ - -/** - * @class OO.ui.mixin.TabIndexedElement - * @source - */ - -/** - * @class OO.ui.mixin.TitledElement - * @source - */ - -/** - * @class OO.ui.MultilineTextInputWidget - * @source - */ - -/** - * @class OO.ui.MultioptionWidget - * @source - */ - -/** - * @class OO.ui.MultiselectWidget - * @source - */ - -/** - * @class OO.ui.NumberInputWidget - * @source - */ - -/** - * @class OO.ui.OptionWidget - * @source - */ - -/** - * @class OO.ui.OutlineControlsWidget - * @source - */ - -/** - * @class OO.ui.OutlineOptionWidget - * @source - */ - -/** - * @class OO.ui.OutlineSelectWidget - * @source - */ - -/** - * @class OO.ui.PageLayout - * @source - */ - -/** - * @class OO.ui.PanelLayout - * @source - */ - -/** - * @class OO.ui.PopupButtonWidget - * @source - */ - -/** - * @class OO.ui.PopupTagMultiselectWidget - * @source - */ - -/** - * @class OO.ui.PopupTool - * @source - */ - -/** - * @class OO.ui.PopupToolGroup - * @source - */ - -/** - * @class OO.ui.PopupWidget - * @source - */ - -/** - * @class OO.ui.Process - * @source - */ - -/** - * @class OO.ui.ProcessDialog - * @source - */ - -/** - * @class OO.ui.ProgressBarWidget - * @source - */ - -/** - * @class OO.ui.RadioInputWidget - * @source - */ - -/** - * @class OO.ui.RadioOptionWidget - * @source - */ - -/** - * @class OO.ui.RadioSelectInputWidget - * @source - */ - -/** - * @class OO.ui.RadioSelectWidget - * @source - */ - -/** - * @class OO.ui.SearchInputWidget - * @source - */ - -/** - * @class OO.ui.SearchWidget - * @source - */ - -/** - * @class OO.ui.SelectFileInputWidget - * @source - */ - -/** - * @class OO.ui.SelectWidget - * @source - */ - -/** - * @class OO.ui.StackLayout - * @source - */ - -/** - * @class OO.ui.TabOptionWidget - * @source - */ - -/** - * @class OO.ui.TabPanelLayout - * @source - */ - -/** - * @class OO.ui.TabSelectWidget - * @source - */ - -/** - * @class OO.ui.TagItemWidget - * @source - */ - -/** - * @class OO.ui.TagMultiselectWidget - * @source - */ - -/** - * @class OO.ui.TextInputWidget - * @source - */ - -/** - * @class OO.ui.Theme - * @source - */ - -/** - * @class OO.ui.ToggleButtonWidget - * @source - */ - -/** - * @class OO.ui.ToggleSwitchWidget - * @source - */ - -/** - * @class OO.ui.ToggleWidget - * @source - */ - -/** - * @class OO.ui.Tool - * @source - */ - -/** - * @class OO.ui.Toolbar - * @source - */ - -/** - * @class OO.ui.ToolFactory - * @source - */ - -/** - * @class OO.ui.ToolGroup - * @source - */ - -/** - * @class OO.ui.ToolGroupFactory - * @source - */ - -/** - * @class OO.ui.ToolGroupTool - * @source - */ - -/** - * @class OO.ui.Widget - * @source - */ - -/** - * @class OO.ui.WikimediaUITheme - * @source - */ - -/** - * @class OO.ui.Window - * @source - */ - -/** - * @class OO.ui.WindowInstance - * @source - */ - -/** - * @class OO.ui.WindowManager - * @source - */ diff --git a/.jsduck/external.js b/.jsduck/external.js deleted file mode 100644 index 9ea2d8386..000000000 --- a/.jsduck/external.js +++ /dev/null @@ -1,84 +0,0 @@ -/** - * @class jQuery - * @source - */ - -/** - * @method ajax - * @source - * @return {jqXHR} - */ - -/** - * @class jQuery.Event - * @source - */ - -/** - * @class jQuery.Promise - * @source - */ - -/** - * @class jQuery.Deferred - * @mixins jQuery.Promise - * @source - */ - -/** - * @class jQuery.jqXHR - * @source - * @alternateClassName jqXHR - */ - -/** - * @class QUnit - * @source - */ - -/** - * Source: - * @class OO - */ - -/** - * Source: - * @class OO.EventEmitter - */ - -/** - * Source: - * @class OO.EmitterList - */ - -/** - * Source: - * @class OO.Factory - */ - -/** - * Source: - * @class OO.Registry - */ - -/** - * Source: - * @class OO.SortedEmitterList - */ - -/** - * @class diff_match_patch - * @source - */ - -/** - * @class Map - */ - -/** - * @class Set - */ - -/** - * @class MutationRecord - */ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b9b8748b8..3d3f2a42b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,43 +44,8 @@ To run the tests in a web browser, open `tests/index.html`. ## Building documentation -VisualEditor uses [JSDuck](https://github.com/senchalabs/jsduck) to process -documentation comments embedded in the code. To build the documentation, you -will need `ruby`, `gem`, and `jsduck` installed. - -### Installing ruby and gem - -You're mostly on your own here, but we can give some hints for Mac OS X. - -##### Installing Gem in Mac OS X -Ruby ships with OSX but may be outdated. Use [Homebrew](http://mxcl.github.com/homebrew/): -```sh -$ brew install ruby -``` - -If you've never used `gem` before, don't forget to add the gem's bin to your -`PATH` ([howto](http://stackoverflow.com/a/14138490/319266)). - -### Installing jsduck - -Once you have gem, installing [JSDuck](https://github.com/senchalabs/jsduck) is easy: -```sh -$ gem install --user-install jsduck -``` - -### Running jsduck - -Creating the documentation is easy: -```sh -$ cd VisualEditor -$ npm run doc -``` - -The generated documentation is in the `docs/` subdirectory. View the -documentation in a web browser by opening `docs/index.html`. - -Note that `jsduck` doesn't support live previews when browsing using the -`file:` protocol; this only works when using HTTP/HTTPS. +VisualEditor uses [jsdoc](https://jsdoc.app/) to process documentation comments +embedded in the code. To build the documentation, you will need to run `npm run doc`. ## VisualEditor Code Guidelines @@ -93,7 +58,7 @@ Git commit messages should follow the conventions described in ### Documentation comments -In addition to the [MediaWiki conventions for JSDuck](https://www.mediawiki.org/wiki/Manual:Coding_conventions/JavaScript#Documentation): +In addition to the [MediaWiki conventions for JavaScript documentation](https://www.mediawiki.org/wiki/Manual:Coding_conventions/JavaScript#Documentation): We have the following custom tags: @@ -114,11 +79,8 @@ indicating their order between the standard tags. * @fires name * @return -## Add a new javascript class +### Adding a new JavaScript class -When a new javascript class is added, the file must be referenced in a number of places -before it can be used: - -* .jsduck/categories.json in General->Utilities (or somewhere more specific) -* build/modules.json in visualEditor.core.build (or somewhere more specific) -* Run `grunt build` +When a new JavaScript class is added, the file must be referenced in the build manifest +before it can be used. Add the file to build/modules.json in visualEditor.core.build (or +somewhere more specific), and then run `grunt build`. diff --git a/Gruntfile.js b/Gruntfile.js index 21672726a..c3d7fcf8d 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -176,19 +176,6 @@ module.exports = function ( grunt ) { } }, buildloader: { - iframe: { - targetFile: '.jsduck/eg-iframe.html', - template: '.jsduck/eg-iframe.html.template', - modules: modules, - load: [ - 'visualEditor.standalone.apex.dist', - 'visualEditor.standalone.read' - ], - pathPrefix: '../', - i18n: [ 'i18n/', 'lib/oojs-ui/i18n/' ], - indent: '\t\t', - dir: 'ltr' - }, desktopDemoApex: { targetFile: 'demos/ve/desktop.html', template: 'demos/ve/demo.html.template', diff --git a/jsduck.json b/jsduck.json deleted file mode 100644 index 7c5e7bcbe..000000000 --- a/jsduck.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "--title": "VisualEditor - Documentation", - "--output": "docs", - "--categories": ".jsduck/categories.json", - "--eg-iframe": ".jsduck/eg-iframe.html", - "--tags": ".jsduck/CustomTags.rb", - "--warnings": [ "-nodoc(class,public)", "-global", "-inheritdoc" ], - "--builtin-classes": true, - "--processes": "0", - "--warnings-exit-nonzero": true, - "--external": "HTMLDocument,HTMLBodyElement,HTMLHtmlElement,Window,Node,Text,Map,Set,Range,Selection,ClientRect,File,FileList,Blob,DataTransfer,DataTransferItem,KeyboardEvent,MouseEvent,Promise,Storage", - "--exclude": [ - "rebaser/src/dm/" - ], - "--": [ - ".jsduck/external.js", - ".jsduck/external-ooui.js", - "lib/unicodejs/unicodejs.js", - "lib/treeDiffer/treeDiffer-dist.js", - "src" - ] -} diff --git a/package-lock.json b/package-lock.json index bd7a91bea..fc1f3418d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -26,6 +26,9 @@ "grunt-karma": "4.0.2", "grunt-stylelint": "0.19.0", "grunt-tyops": "0.1.1", + "jsdoc": "4.0.2", + "jsdoc-class-hierarchy": "1.1.2", + "jsdoc-wmf-theme": "1.0.0", "karma": "6.4.2", "karma-chrome-launcher": "3.2.0", "karma-coverage": "2.2.0", @@ -796,6 +799,18 @@ "integrity": "sha512-XPSJHWmi394fuUuzDnGz1wiKqWfo1yXecHQMRf2l6hztTO+nPru658AyDngaBe7isIxEkRsPR3FZh+s7iVa4Uw==", "dev": true }, + "node_modules/@jsdoc/salty": { + "version": "0.2.8", + "resolved": "https://registry.npmjs.org/@jsdoc/salty/-/salty-0.2.8.tgz", + "integrity": "sha512-5e+SFVavj1ORKlKaKr2BmTOekmXbelU7dC0cDkQLqag7xfuTPuGMUFx7KWJuv4bYZrTsoL2Z18VVCOKYxzoHcg==", + "dev": true, + "dependencies": { + "lodash": "^4.17.21" + }, + "engines": { + "node": ">=v12.0.0" + } + }, "node_modules/@mdn/browser-compat-data": { "version": "5.4.1", "resolved": "https://registry.npmjs.org/@mdn/browser-compat-data/-/browser-compat-data-5.4.1.tgz", @@ -873,6 +888,28 @@ "integrity": "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==", "dev": true }, + "node_modules/@types/linkify-it": { + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/@types/linkify-it/-/linkify-it-3.0.5.tgz", + "integrity": "sha512-yg6E+u0/+Zjva+buc3EIb+29XEg4wltq7cSmd4Uc2EE/1nUVmxyzpX6gUXD0V8jIrG0r7YeOGVIbYRkxeooCtw==", + "dev": true + }, + "node_modules/@types/markdown-it": { + "version": "12.2.3", + "resolved": "https://registry.npmjs.org/@types/markdown-it/-/markdown-it-12.2.3.tgz", + "integrity": "sha512-GKMHFfv3458yYy+v/N8gjufHO6MSZKCOXpZc5GXIWWy8uldwfmPn98vp81gZ5f9SVw8YYBctgfJ22a2d7AOMeQ==", + "dev": true, + "dependencies": { + "@types/linkify-it": "*", + "@types/mdurl": "*" + } + }, + "node_modules/@types/mdurl": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/@types/mdurl/-/mdurl-1.0.5.tgz", + "integrity": "sha512-6L6VymKTzYSrEf4Nev4Xa1LCHKrlTlYCBMTlQKFuddo1CvQcE52I0mwfOJayueUC7MJuXOeHTcIU683lzd0cUA==", + "dev": true + }, "node_modules/@types/minimatch": { "version": "3.0.5", "resolved": "https://registry.npmjs.org/@types/minimatch/-/minimatch-3.0.5.tgz", @@ -1031,6 +1068,16 @@ "integrity": "sha512-zuVdFrMJiuCDQUMCzQaD6KL28MjnqqN8XnAqiEq9PNm/hCPTSGfrXCOfwj1ow4LFb/tNymJPwsNbVePc1xFqrQ==", "dev": true }, + "node_modules/@wikimedia/codex-design-tokens": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@wikimedia/codex-design-tokens/-/codex-design-tokens-1.1.1.tgz", + "integrity": "sha512-qFX7LcR/l90yqVTBApvrIDY3Xa0WifoMlBJRGD1DoWff8e/yMhLmxF1o2DRcIfQlOvKDg0Vhy8jAttF6MUfMAA==", + "dev": true, + "engines": { + "node": ">=16", + "npm": ">=7.21.0" + } + }, "node_modules/abbrev": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", @@ -1283,6 +1330,12 @@ "node": ">=8" } }, + "node_modules/bluebird": { + "version": "3.7.2", + "resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.7.2.tgz", + "integrity": "sha512-XpNj6GDQzdfW+r2Wnn7xiSAd7TM3jzkxGXBGTtWKuSXv1xUV+azxAm8jdWZN06QTQk+2N2XB9jRDkvbmQmcRtg==", + "dev": true + }, "node_modules/body": { "version": "5.1.0", "resolved": "https://registry.npmjs.org/body/-/body-5.1.0.tgz", @@ -1514,9 +1567,9 @@ } }, "node_modules/caniuse-lite": { - "version": "1.0.30001611", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001611.tgz", - "integrity": "sha512-19NuN1/3PjA3QI8Eki55N8my4LzfkMCRLgCVfrl/slbSAchQfV0+GwjPrK3rq37As4UCLlM/DHajbKkAqbv92Q==", + "version": "1.0.30001612", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001612.tgz", + "integrity": "sha512-lFgnZ07UhaCcsSZgWW0K5j4e69dK1u/ltrL9lTUiFOwNHs12S3UMIEYgBV0Z6C6hRDev7iRnMzzYmKabYdXF9g==", "dev": true, "funding": [ { @@ -1539,6 +1592,18 @@ "integrity": "sha1-G2gcIf+EAzyCZUMJBolCDRhxUdw=", "dev": true }, + "node_modules/catharsis": { + "version": "0.9.0", + "resolved": "https://registry.npmjs.org/catharsis/-/catharsis-0.9.0.tgz", + "integrity": "sha512-prMTQVpcns/tzFgFVkVp6ak6RykZyWb3gu8ckUpd6YkTlacOd3DXGJjIpD4Q6zJirizvaiAjSSHlOsA+6sNh2A==", + "dev": true, + "dependencies": { + "lodash": "^4.17.15" + }, + "engines": { + "node": ">= 10" + } + }, "node_modules/chalk": { "version": "4.1.2", "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", @@ -2255,6 +2320,12 @@ "url": "https://github.com/fb55/domhandler?sponsor=1" } }, + "node_modules/domino": { + "version": "2.1.6", + "resolved": "https://registry.npmjs.org/domino/-/domino-2.1.6.tgz", + "integrity": "sha512-3VdM/SXBZX2omc9JF9nOPCtDaYQ67BGp5CoLpIQlO2KCAPETs8TcDHacF26jXadGbvUteZzRTeos2fhID5+ucQ==", + "dev": true + }, "node_modules/domutils": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/domutils/-/domutils-3.1.0.tgz", @@ -2295,9 +2366,9 @@ "dev": true }, "node_modules/electron-to-chromium": { - "version": "1.4.741", - "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.741.tgz", - "integrity": "sha512-AyTBZqDoS7/mvQK22gOQpjxbeV8iPeUBTvYlEh/1S9dKAHgQdxuF49g9rLbj0cRKtqH8PzLJzqT3nAdl+qoZTA==", + "version": "1.4.748", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.748.tgz", + "integrity": "sha512-VWqjOlPZn70UZ8FTKUOkUvBLeTQ0xpty66qV0yJcAGY2/CthI4xyW9aEozRVtuwv3Kpf5xTesmJUcPwuJmgP4A==", "dev": true }, "node_modules/emoji-regex": { @@ -2657,9 +2728,9 @@ } }, "node_modules/eslint-plugin-mocha": { - "version": "10.4.2", - "resolved": "https://registry.npmjs.org/eslint-plugin-mocha/-/eslint-plugin-mocha-10.4.2.tgz", - "integrity": "sha512-cur4dVYnSEWTBwdqIBQFxa/9siAhesu0TX+lbJ4ClE9j0eNMNe6BSx3vkFFNz6tGoveyMyELFXa30f3fvuAVDg==", + "version": "10.4.3", + "resolved": "https://registry.npmjs.org/eslint-plugin-mocha/-/eslint-plugin-mocha-10.4.3.tgz", + "integrity": "sha512-emc4TVjq5Ht0/upR+psftuz6IBG5q279p+1dSRDeHf+NS9aaerBi3lXKo1SEzwC29hFIW21gO89CEWSvRsi8IQ==", "dev": true, "dependencies": { "eslint-utils": "^3.0.0", @@ -3315,20 +3386,6 @@ "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=", "dev": true }, - "node_modules/fsevents": { - "version": "2.3.2", - "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz", - "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==", - "dev": true, - "hasInstallScript": true, - "optional": true, - "os": [ - "darwin" - ], - "engines": { - "node": "^8.16.0 || ^10.6.0 || >=11.0.0" - } - }, "node_modules/function-bind": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz", @@ -4696,12 +4753,56 @@ "js-yaml": "bin/js-yaml.js" } }, + "node_modules/js2xmlparser": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/js2xmlparser/-/js2xmlparser-4.0.2.tgz", + "integrity": "sha512-6n4D8gLlLf1n5mNLQPRfViYzu9RATblzPEtm1SthMX1Pjao0r9YI9nw7ZIfRxQMERS87mcswrg+r/OYrPRX6jA==", + "dev": true, + "dependencies": { + "xmlcreate": "^2.0.4" + } + }, "node_modules/jsbn": { "version": "0.1.1", "resolved": "https://registry.npmjs.org/jsbn/-/jsbn-0.1.1.tgz", "integrity": "sha1-peZUwuWi3rXyAdls77yoDA7y9RM=", "dev": true }, + "node_modules/jsdoc": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/jsdoc/-/jsdoc-4.0.2.tgz", + "integrity": "sha512-e8cIg2z62InH7azBBi3EsSEqrKx+nUtAS5bBcYTSpZFA+vhNPyhv8PTFZ0WsjOPDj04/dOLlm08EDcQJDqaGQg==", + "dev": true, + "dependencies": { + "@babel/parser": "^7.20.15", + "@jsdoc/salty": "^0.2.1", + "@types/markdown-it": "^12.2.3", + "bluebird": "^3.7.2", + "catharsis": "^0.9.0", + "escape-string-regexp": "^2.0.0", + "js2xmlparser": "^4.0.2", + "klaw": "^3.0.0", + "markdown-it": "^12.3.2", + "markdown-it-anchor": "^8.4.1", + "marked": "^4.0.10", + "mkdirp": "^1.0.4", + "requizzle": "^0.2.3", + "strip-json-comments": "^3.1.0", + "underscore": "~1.13.2" + }, + "bin": { + "jsdoc": "jsdoc.js" + }, + "engines": { + "node": ">=12.0.0" + } + }, + "node_modules/jsdoc-class-hierarchy": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/jsdoc-class-hierarchy/-/jsdoc-class-hierarchy-1.1.2.tgz", + "integrity": "sha512-oU7UgWr0Qbtxd2J81/ee1lM8xAdyUU7B1ZosVwZxJwjhPWvtkX9ooHjD1Fk97OyOlpTBXxYVTpptvSCKRt8wvQ==", + "dev": true + }, "node_modules/jsdoc-type-pratt-parser": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-4.0.0.tgz", @@ -4711,6 +4812,53 @@ "node": ">=12.0.0" } }, + "node_modules/jsdoc-wmf-theme": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/jsdoc-wmf-theme/-/jsdoc-wmf-theme-1.0.0.tgz", + "integrity": "sha512-DAR0Rna+X5/Hzlmt297Y05BLPGdUfBUBXfdMwiSJjh8cpLZxt9lHjw2SYnzOpPAPuJYWW3t6MkoJMG0i9cv+uQ==", + "dev": true, + "dependencies": { + "@jsdoc/salty": "^0.2.7", + "@wikimedia/codex-design-tokens": "1.1.1", + "domino": "^2.1.6", + "lunr": "2.3.9", + "marked": "^12.0.1", + "normalize.css": "8.0.1" + } + }, + "node_modules/jsdoc-wmf-theme/node_modules/marked": { + "version": "12.0.2", + "resolved": "https://registry.npmjs.org/marked/-/marked-12.0.2.tgz", + "integrity": "sha512-qXUm7e/YKFoqFPYPa3Ukg9xlI5cyAtGmyEIzMfW//m6kXwCy2Ps9DYf5ioijFKQ8qyuscrHoY04iJGctu2Kg0Q==", + "dev": true, + "bin": { + "marked": "bin/marked.js" + }, + "engines": { + "node": ">= 18" + } + }, + "node_modules/jsdoc/node_modules/escape-string-regexp": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz", + "integrity": "sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/jsdoc/node_modules/mkdirp": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz", + "integrity": "sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==", + "dev": true, + "bin": { + "mkdirp": "bin/cmd.js" + }, + "engines": { + "node": ">=10" + } + }, "node_modules/jsesc": { "version": "2.5.2", "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-2.5.2.tgz", @@ -5024,6 +5172,15 @@ "node": ">=0.10.0" } }, + "node_modules/klaw": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/klaw/-/klaw-3.0.0.tgz", + "integrity": "sha512-0Fo5oir+O9jnXu5EefYbVK+mHMBeEVEy2cmctR1O1NECcCkPRreJKrS6Qt/j3KC2C148Dfo9i3pCmCMsdqGr0g==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.1.9" + } + }, "node_modules/known-css-properties": { "version": "0.28.0", "resolved": "https://registry.npmjs.org/known-css-properties/-/known-css-properties-0.28.0.tgz", @@ -5195,6 +5352,15 @@ "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==", "dev": true }, + "node_modules/linkify-it": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-3.0.3.tgz", + "integrity": "sha512-ynTsyrFSdE5oZ/O9GEf00kPngmOfVwazR5GKDq6EYfhlpFug3J2zybX56a2PRRpc9P+FuSoGNAwjlbDs9jJBPQ==", + "dev": true, + "dependencies": { + "uc.micro": "^1.0.1" + } + }, "node_modules/livereload-js": { "version": "2.4.0", "resolved": "https://registry.npmjs.org/livereload-js/-/livereload-js-2.4.0.tgz", @@ -5351,6 +5517,12 @@ "node": ">=10" } }, + "node_modules/lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true + }, "node_modules/make-dir": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-3.1.0.tgz", @@ -5408,6 +5580,53 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/markdown-it": { + "version": "12.3.2", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-12.3.2.tgz", + "integrity": "sha512-TchMembfxfNVpHkbtriWltGWc+m3xszaRD0CZup7GFFhzIgQqxIfn3eGj1yZpfuflzPvfkt611B2Q/Bsk1YnGg==", + "dev": true, + "dependencies": { + "argparse": "^2.0.1", + "entities": "~2.1.0", + "linkify-it": "^3.0.1", + "mdurl": "^1.0.1", + "uc.micro": "^1.0.5" + }, + "bin": { + "markdown-it": "bin/markdown-it.js" + } + }, + "node_modules/markdown-it-anchor": { + "version": "8.6.7", + "resolved": "https://registry.npmjs.org/markdown-it-anchor/-/markdown-it-anchor-8.6.7.tgz", + "integrity": "sha512-FlCHFwNnutLgVTflOYHPW2pPcl2AACqVzExlkGQNsi4CJgqOHN7YTgDd4LuhgN1BFO3TS0vLAruV1Td6dwWPJA==", + "dev": true, + "peerDependencies": { + "@types/markdown-it": "*", + "markdown-it": "*" + } + }, + "node_modules/markdown-it/node_modules/entities": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-2.1.0.tgz", + "integrity": "sha512-hCx1oky9PFrJ611mf0ifBLBRW8lUUVRlFolb5gWRfIELabBlbp9xZvrqZLZAs+NxFnbfQoeGd8wDkygjg7U85w==", + "dev": true, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, + "node_modules/marked": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/marked/-/marked-4.3.0.tgz", + "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==", + "dev": true, + "bin": { + "marked": "bin/marked.js" + }, + "engines": { + "node": ">= 12" + } + }, "node_modules/mathml-tag-names": { "version": "2.1.3", "resolved": "https://registry.npmjs.org/mathml-tag-names/-/mathml-tag-names-2.1.3.tgz", @@ -5424,6 +5643,12 @@ "integrity": "sha512-GaqWWShW4kv/G9IEucWScBx9G1/vsFZZJUO+tD26M8J8z3Kw5RDQjaoZe03YAClgeS/SWPOcb4nkFBTEi5DUEA==", "dev": true }, + "node_modules/mdurl": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-1.0.1.tgz", + "integrity": "sha512-/sKlQJCBYVY9Ers9hqzKou4H6V5UWc/M59TH2dvkt+84itfnq7uFOMLpOiOS4ujvHP4etln18fmIxA5R5fll0g==", + "dev": true + }, "node_modules/media-typer": { "version": "0.3.0", "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-0.3.0.tgz", @@ -5828,6 +6053,12 @@ "node": ">=0.10.0" } }, + "node_modules/normalize.css": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/normalize.css/-/normalize.css-8.0.1.tgz", + "integrity": "sha512-qizSNPO93t1YUuUhP22btGOo3chcvDFqFaj2TRybP0DMxkHOCTYwp3n34fel4a31ORXy4m1Xq0Gyqpb5m33qIg==", + "dev": true + }, "node_modules/nth-check": { "version": "2.1.1", "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz", @@ -6722,6 +6953,15 @@ "integrity": "sha1-kl0mAdOaxIXgkc8NpcbmlNw9yv8=", "dev": true }, + "node_modules/requizzle": { + "version": "0.2.4", + "resolved": "https://registry.npmjs.org/requizzle/-/requizzle-0.2.4.tgz", + "integrity": "sha512-JRrFk1D4OQ4SqovXOgdav+K8EAhSB/LJZqCz8tbX0KObcdeM15Ss59ozWMBWmmINMagCwmqn4ZNryUGpBsl6Jw==", + "dev": true, + "dependencies": { + "lodash": "^4.17.21" + } + }, "node_modules/resolve": { "version": "1.22.8", "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.8.tgz", @@ -7869,6 +8109,12 @@ "node": "*" } }, + "node_modules/uc.micro": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-1.0.6.tgz", + "integrity": "sha512-8Y75pvTYkLJW2hWQHXxoqRgV7qb9B+9vFEtidML+7koHUFapnVJAZ6cKs+Qjz5Aw3aZWHMC6u0wJE3At+nSGwA==", + "dev": true + }, "node_modules/unc-path-regex": { "version": "0.1.2", "resolved": "https://registry.npmjs.org/unc-path-regex/-/unc-path-regex-0.1.2.tgz", @@ -7878,6 +8124,12 @@ "node": ">=0.10.0" } }, + "node_modules/underscore": { + "version": "1.13.6", + "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.13.6.tgz", + "integrity": "sha512-+A5Sja4HP1M08MaXya7p5LvjuM7K6q/2EaC0+iovj/wOcMsTzMvDFbasi/oSapiwOlt252IqsKqPjCl7huKS0A==", + "dev": true + }, "node_modules/underscore.string": { "version": "3.3.6", "resolved": "https://registry.npmjs.org/underscore.string/-/underscore.string-3.3.6.tgz", @@ -8171,6 +8423,12 @@ "node": ">=12" } }, + "node_modules/xmlcreate": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/xmlcreate/-/xmlcreate-2.0.4.tgz", + "integrity": "sha512-nquOebG4sngPmGPICTS5EnxqhKbCmz5Ox5hsszI2T6U5qdrJizBc+0ilYSEjTSzU0yZcmvppztXe/5Al5fUwdg==", + "dev": true + }, "node_modules/xtend": { "version": "4.0.2", "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz", @@ -8812,6 +9070,15 @@ } } }, + "@jsdoc/salty": { + "version": "0.2.8", + "resolved": "https://registry.npmjs.org/@jsdoc/salty/-/salty-0.2.8.tgz", + "integrity": "sha512-5e+SFVavj1ORKlKaKr2BmTOekmXbelU7dC0cDkQLqag7xfuTPuGMUFx7KWJuv4bYZrTsoL2Z18VVCOKYxzoHcg==", + "dev": true, + "requires": { + "lodash": "^4.17.21" + } + }, "@mdn/browser-compat-data": { "version": "5.4.1", "resolved": "https://registry.npmjs.org/@mdn/browser-compat-data/-/browser-compat-data-5.4.1.tgz", @@ -8877,6 +9144,28 @@ "integrity": "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==", "dev": true }, + "@types/linkify-it": { + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/@types/linkify-it/-/linkify-it-3.0.5.tgz", + "integrity": "sha512-yg6E+u0/+Zjva+buc3EIb+29XEg4wltq7cSmd4Uc2EE/1nUVmxyzpX6gUXD0V8jIrG0r7YeOGVIbYRkxeooCtw==", + "dev": true + }, + "@types/markdown-it": { + "version": "12.2.3", + "resolved": "https://registry.npmjs.org/@types/markdown-it/-/markdown-it-12.2.3.tgz", + "integrity": "sha512-GKMHFfv3458yYy+v/N8gjufHO6MSZKCOXpZc5GXIWWy8uldwfmPn98vp81gZ5f9SVw8YYBctgfJ22a2d7AOMeQ==", + "dev": true, + "requires": { + "@types/linkify-it": "*", + "@types/mdurl": "*" + } + }, + "@types/mdurl": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/@types/mdurl/-/mdurl-1.0.5.tgz", + "integrity": "sha512-6L6VymKTzYSrEf4Nev4Xa1LCHKrlTlYCBMTlQKFuddo1CvQcE52I0mwfOJayueUC7MJuXOeHTcIU683lzd0cUA==", + "dev": true + }, "@types/minimatch": { "version": "3.0.5", "resolved": "https://registry.npmjs.org/@types/minimatch/-/minimatch-3.0.5.tgz", @@ -8988,6 +9277,12 @@ "integrity": "sha512-zuVdFrMJiuCDQUMCzQaD6KL28MjnqqN8XnAqiEq9PNm/hCPTSGfrXCOfwj1ow4LFb/tNymJPwsNbVePc1xFqrQ==", "dev": true }, + "@wikimedia/codex-design-tokens": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@wikimedia/codex-design-tokens/-/codex-design-tokens-1.1.1.tgz", + "integrity": "sha512-qFX7LcR/l90yqVTBApvrIDY3Xa0WifoMlBJRGD1DoWff8e/yMhLmxF1o2DRcIfQlOvKDg0Vhy8jAttF6MUfMAA==", + "dev": true + }, "abbrev": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", @@ -9180,6 +9475,12 @@ "integrity": "sha512-jDctJ/IVQbZoJykoeHbhXpOlNBqGNcwXJKJog42E5HDPUwQTSdjCHdihjj0DlnheQ7blbT6dHOafNAiS8ooQKA==", "dev": true }, + "bluebird": { + "version": "3.7.2", + "resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.7.2.tgz", + "integrity": "sha512-XpNj6GDQzdfW+r2Wnn7xiSAd7TM3jzkxGXBGTtWKuSXv1xUV+azxAm8jdWZN06QTQk+2N2XB9jRDkvbmQmcRtg==", + "dev": true + }, "body": { "version": "5.1.0", "resolved": "https://registry.npmjs.org/body/-/body-5.1.0.tgz", @@ -9354,9 +9655,9 @@ } }, "caniuse-lite": { - "version": "1.0.30001611", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001611.tgz", - "integrity": "sha512-19NuN1/3PjA3QI8Eki55N8my4LzfkMCRLgCVfrl/slbSAchQfV0+GwjPrK3rq37As4UCLlM/DHajbKkAqbv92Q==", + "version": "1.0.30001612", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001612.tgz", + "integrity": "sha512-lFgnZ07UhaCcsSZgWW0K5j4e69dK1u/ltrL9lTUiFOwNHs12S3UMIEYgBV0Z6C6hRDev7iRnMzzYmKabYdXF9g==", "dev": true }, "caseless": { @@ -9365,6 +9666,15 @@ "integrity": "sha1-G2gcIf+EAzyCZUMJBolCDRhxUdw=", "dev": true }, + "catharsis": { + "version": "0.9.0", + "resolved": "https://registry.npmjs.org/catharsis/-/catharsis-0.9.0.tgz", + "integrity": "sha512-prMTQVpcns/tzFgFVkVp6ak6RykZyWb3gu8ckUpd6YkTlacOd3DXGJjIpD4Q6zJirizvaiAjSSHlOsA+6sNh2A==", + "dev": true, + "requires": { + "lodash": "^4.17.15" + } + }, "chalk": { "version": "4.1.2", "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", @@ -9904,6 +10214,12 @@ "domelementtype": "^2.3.0" } }, + "domino": { + "version": "2.1.6", + "resolved": "https://registry.npmjs.org/domino/-/domino-2.1.6.tgz", + "integrity": "sha512-3VdM/SXBZX2omc9JF9nOPCtDaYQ67BGp5CoLpIQlO2KCAPETs8TcDHacF26jXadGbvUteZzRTeos2fhID5+ucQ==", + "dev": true + }, "domutils": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/domutils/-/domutils-3.1.0.tgz", @@ -9941,9 +10257,9 @@ "dev": true }, "electron-to-chromium": { - "version": "1.4.741", - "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.741.tgz", - "integrity": "sha512-AyTBZqDoS7/mvQK22gOQpjxbeV8iPeUBTvYlEh/1S9dKAHgQdxuF49g9rLbj0cRKtqH8PzLJzqT3nAdl+qoZTA==", + "version": "1.4.748", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.748.tgz", + "integrity": "sha512-VWqjOlPZn70UZ8FTKUOkUvBLeTQ0xpty66qV0yJcAGY2/CthI4xyW9aEozRVtuwv3Kpf5xTesmJUcPwuJmgP4A==", "dev": true }, "emoji-regex": { @@ -10222,9 +10538,9 @@ } }, "eslint-plugin-mocha": { - "version": "10.4.2", - "resolved": "https://registry.npmjs.org/eslint-plugin-mocha/-/eslint-plugin-mocha-10.4.2.tgz", - "integrity": "sha512-cur4dVYnSEWTBwdqIBQFxa/9siAhesu0TX+lbJ4ClE9j0eNMNe6BSx3vkFFNz6tGoveyMyELFXa30f3fvuAVDg==", + "version": "10.4.3", + "resolved": "https://registry.npmjs.org/eslint-plugin-mocha/-/eslint-plugin-mocha-10.4.3.tgz", + "integrity": "sha512-emc4TVjq5Ht0/upR+psftuz6IBG5q279p+1dSRDeHf+NS9aaerBi3lXKo1SEzwC29hFIW21gO89CEWSvRsi8IQ==", "dev": true, "requires": { "eslint-utils": "^3.0.0", @@ -10706,13 +11022,6 @@ "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=", "dev": true }, - "fsevents": { - "version": "2.3.2", - "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz", - "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==", - "dev": true, - "optional": true - }, "function-bind": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz", @@ -11747,18 +12056,92 @@ "argparse": "^2.0.1" } }, + "js2xmlparser": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/js2xmlparser/-/js2xmlparser-4.0.2.tgz", + "integrity": "sha512-6n4D8gLlLf1n5mNLQPRfViYzu9RATblzPEtm1SthMX1Pjao0r9YI9nw7ZIfRxQMERS87mcswrg+r/OYrPRX6jA==", + "dev": true, + "requires": { + "xmlcreate": "^2.0.4" + } + }, "jsbn": { "version": "0.1.1", "resolved": "https://registry.npmjs.org/jsbn/-/jsbn-0.1.1.tgz", "integrity": "sha1-peZUwuWi3rXyAdls77yoDA7y9RM=", "dev": true }, + "jsdoc": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/jsdoc/-/jsdoc-4.0.2.tgz", + "integrity": "sha512-e8cIg2z62InH7azBBi3EsSEqrKx+nUtAS5bBcYTSpZFA+vhNPyhv8PTFZ0WsjOPDj04/dOLlm08EDcQJDqaGQg==", + "dev": true, + "requires": { + "@babel/parser": "^7.20.15", + "@jsdoc/salty": "^0.2.1", + "@types/markdown-it": "^12.2.3", + "bluebird": "^3.7.2", + "catharsis": "^0.9.0", + "escape-string-regexp": "^2.0.0", + "js2xmlparser": "^4.0.2", + "klaw": "^3.0.0", + "markdown-it": "^12.3.2", + "markdown-it-anchor": "^8.4.1", + "marked": "^4.0.10", + "mkdirp": "^1.0.4", + "requizzle": "^0.2.3", + "strip-json-comments": "^3.1.0", + "underscore": "~1.13.2" + }, + "dependencies": { + "escape-string-regexp": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz", + "integrity": "sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==", + "dev": true + }, + "mkdirp": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz", + "integrity": "sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==", + "dev": true + } + } + }, + "jsdoc-class-hierarchy": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/jsdoc-class-hierarchy/-/jsdoc-class-hierarchy-1.1.2.tgz", + "integrity": "sha512-oU7UgWr0Qbtxd2J81/ee1lM8xAdyUU7B1ZosVwZxJwjhPWvtkX9ooHjD1Fk97OyOlpTBXxYVTpptvSCKRt8wvQ==", + "dev": true + }, "jsdoc-type-pratt-parser": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-4.0.0.tgz", "integrity": "sha512-YtOli5Cmzy3q4dP26GraSOeAhqecewG04hoO8DY56CH4KJ9Fvv5qKWUCCo3HZob7esJQHCv6/+bnTy72xZZaVQ==", "dev": true }, + "jsdoc-wmf-theme": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/jsdoc-wmf-theme/-/jsdoc-wmf-theme-1.0.0.tgz", + "integrity": "sha512-DAR0Rna+X5/Hzlmt297Y05BLPGdUfBUBXfdMwiSJjh8cpLZxt9lHjw2SYnzOpPAPuJYWW3t6MkoJMG0i9cv+uQ==", + "dev": true, + "requires": { + "@jsdoc/salty": "^0.2.7", + "@wikimedia/codex-design-tokens": "1.1.1", + "domino": "^2.1.6", + "lunr": "2.3.9", + "marked": "^12.0.1", + "normalize.css": "8.0.1" + }, + "dependencies": { + "marked": { + "version": "12.0.2", + "resolved": "https://registry.npmjs.org/marked/-/marked-12.0.2.tgz", + "integrity": "sha512-qXUm7e/YKFoqFPYPa3Ukg9xlI5cyAtGmyEIzMfW//m6kXwCy2Ps9DYf5ioijFKQ8qyuscrHoY04iJGctu2Kg0Q==", + "dev": true + } + } + }, "jsesc": { "version": "2.5.2", "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-2.5.2.tgz", @@ -12010,6 +12393,15 @@ "integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==", "dev": true }, + "klaw": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/klaw/-/klaw-3.0.0.tgz", + "integrity": "sha512-0Fo5oir+O9jnXu5EefYbVK+mHMBeEVEy2cmctR1O1NECcCkPRreJKrS6Qt/j3KC2C148Dfo9i3pCmCMsdqGr0g==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.9" + } + }, "known-css-properties": { "version": "0.28.0", "resolved": "https://registry.npmjs.org/known-css-properties/-/known-css-properties-0.28.0.tgz", @@ -12155,6 +12547,15 @@ "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==", "dev": true }, + "linkify-it": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-3.0.3.tgz", + "integrity": "sha512-ynTsyrFSdE5oZ/O9GEf00kPngmOfVwazR5GKDq6EYfhlpFug3J2zybX56a2PRRpc9P+FuSoGNAwjlbDs9jJBPQ==", + "dev": true, + "requires": { + "uc.micro": "^1.0.1" + } + }, "livereload-js": { "version": "2.4.0", "resolved": "https://registry.npmjs.org/livereload-js/-/livereload-js-2.4.0.tgz", @@ -12283,6 +12684,12 @@ "yallist": "^4.0.0" } }, + "lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true + }, "make-dir": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-3.1.0.tgz", @@ -12321,6 +12728,40 @@ "integrity": "sha512-hdN1wVrZbb29eBGiGjJbeP8JbKjq1urkHJ/LIP/NY48MZ1QVXUsQBV1G1zvYFHn1XE06cwjBsOI2K3Ulnj1YXQ==", "dev": true }, + "markdown-it": { + "version": "12.3.2", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-12.3.2.tgz", + "integrity": "sha512-TchMembfxfNVpHkbtriWltGWc+m3xszaRD0CZup7GFFhzIgQqxIfn3eGj1yZpfuflzPvfkt611B2Q/Bsk1YnGg==", + "dev": true, + "requires": { + "argparse": "^2.0.1", + "entities": "~2.1.0", + "linkify-it": "^3.0.1", + "mdurl": "^1.0.1", + "uc.micro": "^1.0.5" + }, + "dependencies": { + "entities": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-2.1.0.tgz", + "integrity": "sha512-hCx1oky9PFrJ611mf0ifBLBRW8lUUVRlFolb5gWRfIELabBlbp9xZvrqZLZAs+NxFnbfQoeGd8wDkygjg7U85w==", + "dev": true + } + } + }, + "markdown-it-anchor": { + "version": "8.6.7", + "resolved": "https://registry.npmjs.org/markdown-it-anchor/-/markdown-it-anchor-8.6.7.tgz", + "integrity": "sha512-FlCHFwNnutLgVTflOYHPW2pPcl2AACqVzExlkGQNsi4CJgqOHN7YTgDd4LuhgN1BFO3TS0vLAruV1Td6dwWPJA==", + "dev": true, + "requires": {} + }, + "marked": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/marked/-/marked-4.3.0.tgz", + "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==", + "dev": true + }, "mathml-tag-names": { "version": "2.1.3", "resolved": "https://registry.npmjs.org/mathml-tag-names/-/mathml-tag-names-2.1.3.tgz", @@ -12333,6 +12774,12 @@ "integrity": "sha512-GaqWWShW4kv/G9IEucWScBx9G1/vsFZZJUO+tD26M8J8z3Kw5RDQjaoZe03YAClgeS/SWPOcb4nkFBTEi5DUEA==", "dev": true }, + "mdurl": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-1.0.1.tgz", + "integrity": "sha512-/sKlQJCBYVY9Ers9hqzKou4H6V5UWc/M59TH2dvkt+84itfnq7uFOMLpOiOS4ujvHP4etln18fmIxA5R5fll0g==", + "dev": true + }, "media-typer": { "version": "0.3.0", "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-0.3.0.tgz", @@ -12630,6 +13077,12 @@ "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==", "dev": true }, + "normalize.css": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/normalize.css/-/normalize.css-8.0.1.tgz", + "integrity": "sha512-qizSNPO93t1YUuUhP22btGOo3chcvDFqFaj2TRybP0DMxkHOCTYwp3n34fel4a31ORXy4m1Xq0Gyqpb5m33qIg==", + "dev": true + }, "nth-check": { "version": "2.1.1", "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz", @@ -13274,6 +13727,15 @@ "integrity": "sha1-kl0mAdOaxIXgkc8NpcbmlNw9yv8=", "dev": true }, + "requizzle": { + "version": "0.2.4", + "resolved": "https://registry.npmjs.org/requizzle/-/requizzle-0.2.4.tgz", + "integrity": "sha512-JRrFk1D4OQ4SqovXOgdav+K8EAhSB/LJZqCz8tbX0KObcdeM15Ss59ozWMBWmmINMagCwmqn4ZNryUGpBsl6Jw==", + "dev": true, + "requires": { + "lodash": "^4.17.21" + } + }, "resolve": { "version": "1.22.8", "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.8.tgz", @@ -14155,12 +14617,24 @@ "integrity": "sha512-cJMeh/eOILyGu0ejgTKB95yKT3zOenSe9UGE3vj6WfiOwgGYnmATUsnDixMFvdU+rNMvWih83hrUP8VwhF9yXQ==", "dev": true }, + "uc.micro": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-1.0.6.tgz", + "integrity": "sha512-8Y75pvTYkLJW2hWQHXxoqRgV7qb9B+9vFEtidML+7koHUFapnVJAZ6cKs+Qjz5Aw3aZWHMC6u0wJE3At+nSGwA==", + "dev": true + }, "unc-path-regex": { "version": "0.1.2", "resolved": "https://registry.npmjs.org/unc-path-regex/-/unc-path-regex-0.1.2.tgz", "integrity": "sha1-5z3T17DXxe2G+6xrCufYxqadUPo=", "dev": true }, + "underscore": { + "version": "1.13.6", + "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.13.6.tgz", + "integrity": "sha512-+A5Sja4HP1M08MaXya7p5LvjuM7K6q/2EaC0+iovj/wOcMsTzMvDFbasi/oSapiwOlt252IqsKqPjCl7huKS0A==", + "dev": true + }, "underscore.string": { "version": "3.3.6", "resolved": "https://registry.npmjs.org/underscore.string/-/underscore.string-3.3.6.tgz", @@ -14357,6 +14831,12 @@ "integrity": "sha512-ICP2e+jsHvAj2E2lIHxa5tjXRlKDJo4IdvPvCXbXQGdzSfmSpNVyIKMvoZHjDY9DP0zV17iI85o90vRFXNccRw==", "dev": true }, + "xmlcreate": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/xmlcreate/-/xmlcreate-2.0.4.tgz", + "integrity": "sha512-nquOebG4sngPmGPICTS5EnxqhKbCmz5Ox5hsszI2T6U5qdrJizBc+0ilYSEjTSzU0yZcmvppztXe/5Al5fUwdg==", + "dev": true + }, "xtend": { "version": "4.0.2", "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz", diff --git a/package.json b/package.json index 857b76ed6..75078b1e0 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,7 @@ "test": "grunt test", "prepare": "grunt build", "postinstall": "cd rebaser && npm ci", - "doc": "jsduck" + "doc": "jsdoc -c .jsdoc.json" }, "homepage": "https://www.mediawiki.org/wiki/VisualEditor", "repository": { @@ -39,6 +39,9 @@ "grunt-karma": "4.0.2", "grunt-stylelint": "0.19.0", "grunt-tyops": "0.1.1", + "jsdoc": "4.0.2", + "jsdoc-class-hierarchy": "1.1.2", + "jsdoc-wmf-theme": "1.0.0", "karma": "6.4.2", "karma-chrome-launcher": "3.2.0", "karma-coverage": "2.2.0", diff --git a/rebaser/src/logToTestCase.js b/rebaser/src/logToTestCase.js index e8a8b7aa2..c2ed7cabf 100644 --- a/rebaser/src/logToTestCase.js +++ b/rebaser/src/logToTestCase.js @@ -7,6 +7,7 @@ const ve = require( '../dist/ve-rebaser.js' ), /** * Parse log file contents. * + * @ignore * @param {string} log Newline-separated list of JSON objects * @return {Object[]} Array of parsed objects */ diff --git a/src/ce/annotations/ve.ce.NailedAnnotation.js b/src/ce/annotations/ve.ce.NailedAnnotation.js index 6eaa6488b..2d1996567 100644 --- a/src/ce/annotations/ve.ce.NailedAnnotation.js +++ b/src/ce/annotations/ve.ce.NailedAnnotation.js @@ -54,15 +54,16 @@ ve.ce.NailedAnnotation.static.makeNail = function ( type ) { /* Methods */ +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.ce.Annotation + * @see ve.ce.Annotation */ ve.ce.NailedAnnotation.prototype.getContentContainer = function () { return this.contentFragment; }; /** - * @inheritdoc ve.ce.Annotation + * @see ve.ce.Annotation */ ve.ce.NailedAnnotation.prototype.attachContents = function () { var element = this.$element[ 0 ]; @@ -72,8 +73,9 @@ ve.ce.NailedAnnotation.prototype.attachContents = function () { element.appendChild( this.constructor.static.makeNail( 'pre-close' ) ); }; +// eslint-disable-next-line jsdoc/require-param /** - * @inheritdoc ve.ce.Annotation + * @see ve.ce.Annotation */ ve.ce.NailedAnnotation.prototype.appendTo = function ( node ) { // Insert pre-open nail, element, and post-close nail into a parent node diff --git a/src/ce/keydownhandlers/ve.ce.LinearEscapeKeyDownHandler.js b/src/ce/keydownhandlers/ve.ce.LinearEscapeKeyDownHandler.js index abd7b2e4d..9cd86c1e6 100644 --- a/src/ce/keydownhandlers/ve.ce.LinearEscapeKeyDownHandler.js +++ b/src/ce/keydownhandlers/ve.ce.LinearEscapeKeyDownHandler.js @@ -33,9 +33,9 @@ ve.ce.LinearEscapeKeyDownHandler.static.supportedSelections = [ 'linear' ]; /* Static methods */ /** - * @inheritdoc - * * Handle escape key down events with a linear selection while table editing. + * + * @inheritdoc */ ve.ce.LinearEscapeKeyDownHandler.static.execute = function ( surface, e ) { var activeTableNode = surface.getActiveNode() && surface.getActiveNode().findParent( ve.ce.TableNode ); diff --git a/src/ce/keydownhandlers/ve.ce.LinearTabKeyDownHandler.js b/src/ce/keydownhandlers/ve.ce.LinearTabKeyDownHandler.js index d817a757f..9ad6428ce 100644 --- a/src/ce/keydownhandlers/ve.ce.LinearTabKeyDownHandler.js +++ b/src/ce/keydownhandlers/ve.ce.LinearTabKeyDownHandler.js @@ -33,9 +33,9 @@ ve.ce.LinearTabKeyDownHandler.static.supportedSelections = [ 'linear' ]; /* Static methods */ /** - * @inheritdoc - * * Handle tab key down events with a linear selection while table editing. + * + * @inheritdoc */ ve.ce.LinearTabKeyDownHandler.static.execute = function ( surface, e ) { var activeTableNode = surface.getActiveNode() && surface.getActiveNode().findParent( ve.ce.TableNode ), diff --git a/src/ce/keydownhandlers/ve.ce.TableDeleteKeyDownHandler.js b/src/ce/keydownhandlers/ve.ce.TableDeleteKeyDownHandler.js index e2f75fea9..d5739f9ef 100644 --- a/src/ce/keydownhandlers/ve.ce.TableDeleteKeyDownHandler.js +++ b/src/ce/keydownhandlers/ve.ce.TableDeleteKeyDownHandler.js @@ -33,11 +33,11 @@ ve.ce.TableDeleteKeyDownHandler.static.supportedSelections = [ 'table' ]; /* Static methods */ /** - * @inheritdoc - * * Handle delete and backspace key down events with a table selection. * * Performs a strip-delete removing all the cell contents but not altering the structure. + * + * @inheritdoc */ ve.ce.TableDeleteKeyDownHandler.static.execute = function ( surface, e ) { var surfaceModel = surface.getModel(), diff --git a/src/ce/nodes/ve.ce.CommentNode.js b/src/ce/nodes/ve.ce.CommentNode.js index 44cc33c0e..d47e09b06 100644 --- a/src/ce/nodes/ve.ce.CommentNode.js +++ b/src/ce/nodes/ve.ce.CommentNode.js @@ -67,8 +67,9 @@ ve.ce.CommentNode.prototype.onAttributeChange = function ( key ) { /* Method */ +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.ce.FocusableNode + * @see ve.ce.FocusableNode */ ve.ce.CommentNode.prototype.hasRendering = function () { // Comment nodes never have a rendering, don't bother with expensive DOM inspection diff --git a/src/ce/nodes/ve.ce.GeneratedContentNode.js b/src/ce/nodes/ve.ce.GeneratedContentNode.js index da1d4e1e2..dad95ab3c 100644 --- a/src/ce/nodes/ve.ce.GeneratedContentNode.js +++ b/src/ce/nodes/ve.ce.GeneratedContentNode.js @@ -32,15 +32,7 @@ OO.initClass( ve.ce.GeneratedContentNode ); /* Events */ /** - * @event setup - */ - -/** - * @event teardown - */ - -/** - * @event rerender + * @event ve.ce.GeneratedContentNode#rerender */ /* Static members */ @@ -184,8 +176,9 @@ ve.ce.GeneratedContentNode.prototype.filterRenderedDomElements = function ( domE * * @param {Object|string|Array} generatedContents Generated contents, in the default case an HTMLElement array * @param {boolean} [staged] Update happened in staging mode - * @fires setup - * @fires teardown + * @fires ve.ce.View#setup + * @fires ve.ce.View#teardown + * @fires ve.dm.GeneratedContentNode#generatedContentsError */ ve.ce.GeneratedContentNode.prototype.render = function ( generatedContents, staged ) { var node = this; @@ -269,7 +262,7 @@ ve.ce.GeneratedContentNode.prototype.preventTabbingInside = function () { * * Nodes may override this method if the rerender event needs to be deferred (e.g. until images have loaded) * - * @fires rerender + * @fires ve.ce.GeneratedContentNode#rerender */ ve.ce.GeneratedContentNode.prototype.afterRender = function () { this.emit( 'rerender' ); diff --git a/src/ce/nodes/ve.ce.ImageNode.js b/src/ce/nodes/ve.ce.ImageNode.js index e60dbbaaa..d01300062 100644 --- a/src/ce/nodes/ve.ce.ImageNode.js +++ b/src/ce/nodes/ve.ce.ImageNode.js @@ -47,8 +47,9 @@ OO.mixinClass( ve.ce.ImageNode, ve.ce.ResizableNode ); /* Static Methods */ +// eslint-disable-next-line jsdoc/require-param, jsdoc/require-returns /** - * @inheritdoc ve.ce.Node + * @see ve.ce.Node */ ve.ce.ImageNode.static.getDescription = function ( model ) { return model.getAttribute( 'src' ); diff --git a/src/ce/nodes/ve.ce.TableCellNode.js b/src/ce/nodes/ve.ce.TableCellNode.js index ffe070b4e..76645bdf3 100644 --- a/src/ce/nodes/ve.ce.TableCellNode.js +++ b/src/ce/nodes/ve.ce.TableCellNode.js @@ -114,8 +114,9 @@ ve.ce.TableCellNode.prototype.onTableCellTeardown = function () { } }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.ce.ContentEditableNode + * @see ve.ce.ContentEditableNode */ ve.ce.TableCellNode.prototype.setContentEditable = function () { // Overwite any state passed to setContentEditable with this.editing, so that diff --git a/src/ce/selections/ve.ce.NullSelection.js b/src/ce/selections/ve.ce.NullSelection.js index 97360ace5..df51f2c41 100644 --- a/src/ce/selections/ve.ce.NullSelection.js +++ b/src/ce/selections/ve.ce.NullSelection.js @@ -63,10 +63,9 @@ ve.ce.NullSelection.prototype.isNativeCursor = function () { /** * @inheritdoc - * - * Null selections don't exist in the view, so just return document directionality. */ ve.ce.NullSelection.prototype.getDirectionality = function ( doc ) { + // Null selections don't exist in the view, so just return document directionality. return doc.getDir(); }; diff --git a/src/ce/ve.ce.AlignableNode.js b/src/ce/ve.ce.AlignableNode.js index b234d96fe..eefddcc22 100644 --- a/src/ce/ve.ce.AlignableNode.js +++ b/src/ce/ve.ce.AlignableNode.js @@ -27,12 +27,13 @@ OO.inheritClass( ve.ce.AlignableNode, ve.ce.ClassAttributeNode ); /* Events */ /** - * @event align + * @event ve.ce.AlignableNode#align * @param {string} align New alignment */ /** * @inheritdoc + * @fires ve.ce.AlignableNode#align */ ve.ce.AlignableNode.prototype.updateAttributeClasses = function () { // Parent method diff --git a/src/ce/ve.ce.BranchNode.js b/src/ce/ve.ce.BranchNode.js index 1db96f10e..b5a59fa1a 100644 --- a/src/ce/ve.ce.BranchNode.js +++ b/src/ce/ve.ce.BranchNode.js @@ -128,8 +128,8 @@ ve.ce.BranchNode.prototype.initialize = function () { * added using $.data() will be lost upon updating the wrapper. To retain information added to the * wrapper, subscribe to the 'teardown' and 'setup' events, or override #initialize. * - * @fires teardown - * @fires setup + * @fires ve.ce.View#teardown + * @fires ve.ce.View#setup */ ve.ce.BranchNode.prototype.updateTagName = function () { var tagName = this.getTagName(); diff --git a/src/ce/ve.ce.ContentBranchNode.js b/src/ce/ve.ce.ContentBranchNode.js index 2cfc12113..e066f1c42 100644 --- a/src/ce/ve.ce.ContentBranchNode.js +++ b/src/ce/ve.ce.ContentBranchNode.js @@ -43,12 +43,11 @@ OO.inheritClass( ve.ce.ContentBranchNode, ve.ce.BranchNode ); /* Static Members */ /** - * Whether Enter splits this node type. Must be true for ContentBranchNodes. + * @property {boolean} Whether Enter splits this node type. Must be true for ContentBranchNodes. * * Warning: overriding this to false in a subclass will cause crashes on Enter key handling. * * @static - * @property {boolean} * @inheritable */ ve.ce.ContentBranchNode.static.splitOnEnter = true; diff --git a/src/ce/ve.ce.Document.js b/src/ce/ve.ce.Document.js index bf0f4b021..a3956db72 100644 --- a/src/ce/ve.ce.Document.js +++ b/src/ce/ve.ce.Document.js @@ -37,7 +37,7 @@ OO.inheritClass( ve.ce.Document, ve.Document ); /** * Language or direction changed * - * @event langChange + * @event ve.ce.Document#langChange */ /* Methods */ diff --git a/src/ce/ve.ce.FocusableNode.js b/src/ce/ve.ce.FocusableNode.js index 5760f0144..d6b278c4a 100644 --- a/src/ce/ve.ce.FocusableNode.js +++ b/src/ce/ve.ce.FocusableNode.js @@ -78,11 +78,11 @@ OO.initClass( ve.ce.FocusableNode ); /* Events */ /** - * @event focus + * @event ve.ce.FocusableNode#focus */ /** - * @event blur + * @event ve.ce.FocusableNode#blur */ /* Static properties */ @@ -617,8 +617,8 @@ ve.ce.FocusableNode.prototype.isFocused = function () { * Set the selected state of the node. * * @param {boolean} value Node is focused - * @fires focus - * @fires blur + * @fires ve.ce.FocusableNode#focus + * @fires ve.ce.FocusableNode#blur */ ve.ce.FocusableNode.prototype.setFocused = function ( value ) { value = !!value; diff --git a/src/ce/ve.ce.Node.js b/src/ce/ve.ce.Node.js index dfd5db47b..0101d4db5 100644 --- a/src/ce/ve.ce.Node.js +++ b/src/ce/ve.ce.Node.js @@ -104,85 +104,97 @@ ve.ce.Node.static.getDescription = function () { /* Methods */ +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.getChildNodeTypes = function () { return this.model.getChildNodeTypes(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.getParentNodeTypes = function () { return this.model.getParentNodeTypes(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.getSuggestedParentNodeTypes = function () { return this.model.getSuggestedParentNodeTypes(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.canHaveChildren = function () { return this.model.canHaveChildren(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.canHaveChildrenNotContent = function () { return this.model.canHaveChildrenNotContent(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.isInternal = function () { return this.model.isInternal(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.isMetaData = function () { return this.model.isMetaData(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.isWrapped = function () { return this.model.isWrapped(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.isUnwrappable = function () { return this.model.isUnwrappable(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.canContainContent = function () { return this.model.canContainContent(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.isContent = function () { return this.model.isContent(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node * * If this is set to true it should implement: * @@ -193,64 +205,73 @@ ve.ce.Node.prototype.isFocusable = function () { return this.model.isFocusable(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.isAlignable = function () { return this.model.isAlignable(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.isCellable = function () { return this.model.isCellable(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.isCellEditable = function () { return this.model.isCellEditable(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.hasSignificantWhitespace = function () { return this.model.hasSignificantWhitespace(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.handlesOwnChildren = function () { return this.model.handlesOwnChildren(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.shouldIgnoreChildren = function () { return this.model.shouldIgnoreChildren(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.getLength = function () { return this.model.getLength(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.getOuterLength = function () { return this.model.getOuterLength(); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.ce.Node.prototype.getOffset = function () { return this.model.getOffset(); diff --git a/src/ce/ve.ce.ResizableNode.js b/src/ce/ve.ce.ResizableNode.js index 0b62d03a8..91a5b3e1e 100644 --- a/src/ce/ve.ce.ResizableNode.js +++ b/src/ce/ve.ce.ResizableNode.js @@ -77,16 +77,16 @@ OO.initClass( ve.ce.ResizableNode ); /* Events */ /** - * @event resizeStart + * @event ve.ce.ResizableNode#resizeStart */ /** - * @event resizing + * @event ve.ce.ResizableNode#resizing * @param {Object} dimensions Dimension object containing width & height */ /** - * @event resizeEnd + * @event ve.ce.ResizableNode#resizeEnd */ /* Methods */ @@ -380,7 +380,7 @@ ve.ce.ResizableNode.prototype.onResizableAttributeChange = function () { * Handle bounding box handle mousedown. * * @param {jQuery.Event} e Click event - * @fires resizeStart + * @fires ve.ce.ResizableNode#resizeStart */ ve.ce.ResizableNode.prototype.onResizeHandlesCornerMouseDown = function ( e ) { // Hide context menu @@ -481,7 +481,7 @@ ve.ce.ResizableNode.prototype.setResizableHandlesPosition = function () { * Handle body mousemove. * * @param {jQuery.Event} e Click event - * @fires resizing + * @fires ve.ce.ResizableNode#resizing */ ve.ce.ResizableNode.prototype.onDocumentMouseMove = function ( e ) { var diff = {}, @@ -548,7 +548,7 @@ ve.ce.ResizableNode.prototype.onDocumentMouseMove = function ( e ) { /** * Handle body mouseup. * - * @fires resizeEnd + * @fires ve.ce.ResizableNode#resizeEnd */ ve.ce.ResizableNode.prototype.onDocumentMouseUp = function () { var width = this.$resizeHandles.outerWidth(), diff --git a/src/ce/ve.ce.Surface.js b/src/ce/ve.ce.Surface.js index 5b1cd180a..ad9929623 100644 --- a/src/ce/ve.ce.Surface.js +++ b/src/ce/ve.ce.Surface.js @@ -242,42 +242,44 @@ OO.mixinClass( ve.ce.Surface, OO.EventEmitter ); /* Events */ /** - * @event relocationStart + * @event ve.ce.Surface#relocationStart */ /** - * @event relocationEnd + * @event ve.ce.Surface#relocationEnd */ /** - * @event keyup + * @event ve.ce.Surface#keyup */ /** * When the surface or its contents changes position * (only after initialize has already been called). * - * @event position + * @event ve.ce.Surface#position */ /** - * @event focus * Note that it's possible for a focus event to occur immediately after a blur event, if the focus * moves to or from a FocusableNode. In this case the surface doesn't lose focus conceptually, but * a pair of blur-focus events is emitted anyway. + * + * @event ve.ce.Surface#focus */ /** - * @event blur * Note that it's possible for a focus event to occur immediately after a blur event, if the focus * moves to or from a FocusableNode. In this case the surface doesn't lose focus conceptually, but * a pair of blur-focus events is emitted anyway. + * + * @event ve.ce.Surface#blur */ /** * Surface activation state has changed (i.e. on activate or deactivate) * - * @event activation + * @event ve.ce.Surface#activation */ /* Static properties */ @@ -516,6 +518,8 @@ ve.ce.Surface.prototype.getSelectionDirectionality = function () { * Initialize surface. * * This should be called after the surface has been attached to the DOM. + * + * @fires ve.ce.Surface#position */ ve.ce.Surface.prototype.initialize = function () { this.attachedRoot.setLive( true ); @@ -745,7 +749,7 @@ ve.ce.Surface.prototype.isShownAsDeactivated = function () { * @param {boolean} [showAsActivated=true] Surface should still show as activated * @param {boolean} [noSelectionChange] Don't change the native selection. * @param {boolean} [hideSelection] Completely hide the selection - * @fires activation + * @fires ve.ce.Surface#activation */ ve.ce.Surface.prototype.deactivate = function ( showAsActivated, noSelectionChange, hideSelection ) { var surface = this; @@ -783,7 +787,8 @@ ve.ce.Surface.prototype.deactivate = function ( showAsActivated, noSelectionChan /** * Reactivate the surface and restore the native selection * - * @fires activation + * @fires ve.ce.Surface#activation + * @fires ve.dm.Surface#contextChange */ ve.ce.Surface.prototype.activate = function () { if ( this.deactivated ) { @@ -1053,7 +1058,7 @@ ve.ce.Surface.prototype.redrawSelections = function () { * * This is triggered by a global focusin/focusout event noticing a selection on the document. * - * @fires focus + * @fires ve.ce.Surface#focus */ ve.ce.Surface.prototype.onDocumentFocus = function () { if ( this.getModel().getSelection().isNull() ) { @@ -1074,7 +1079,7 @@ ve.ce.Surface.prototype.onDocumentFocus = function () { * * This is triggered by a global focusin/focusout event noticing no selection on the document. * - * @fires blur + * @fires ve.ce.Surface#blur */ ve.ce.Surface.prototype.onDocumentBlur = function () { var nullSelectionOnBlur = this.surface.nullSelectionOnBlur; @@ -1328,7 +1333,7 @@ ve.ce.Surface.prototype.onDocumentSelectionChange = function () { * Handle document drag start events. * * @param {jQuery.Event} e Drag start event - * @fires relocationStart + * @fires ve.ce.Surface#relocationStart */ ve.ce.Surface.prototype.onDocumentDragStart = function ( e ) { this.onCopy( e ); @@ -1484,7 +1489,7 @@ ve.ce.Surface.prototype.onDocumentDragLeave = function () { * Limits native drag and drop behaviour. * * @param {jQuery.Event} e Drop event - * @fires relocationEnd + * @fires ve.ce.Surface#relocationEnd */ ve.ce.Surface.prototype.onDocumentDrop = function ( e ) { // Properties may be nullified by other events, so cache before setTimeout @@ -2139,7 +2144,7 @@ ve.ce.Surface.prototype.cleanupUnicorns = function ( fixupCursor ) { * Handle document key up events. * * @param {jQuery.Event} e Key up event - * @fires keyup + * @fires ve.ce.Surface#keyup */ ve.ce.Surface.prototype.onDocumentKeyUp = function () { this.emit( 'keyup' ); @@ -3655,6 +3660,8 @@ ve.ce.Surface.prototype.findFocusedNode = function ( range ) { /** * Handle documentUpdate events on the surface model. + * + * @fires ve.ce.Surface#position */ ve.ce.Surface.prototype.onModelDocumentUpdate = function () { var surface = this; @@ -3888,6 +3895,7 @@ ve.ce.Surface.prototype.handleObservedChanges = function ( oldState, newState ) * Create a slug out of a DOM element * * @param {HTMLElement} element Slug element + * @fires ve.ce.Surface#position */ ve.ce.Surface.prototype.createSlug = function ( element ) { var surface = this, @@ -4128,6 +4136,7 @@ ve.ce.Surface.prototype.maybeSetBreakpoint = function () { * Handle window resize event. * * @param {jQuery.Event} e Window resize event + * @fires ve.ce.Surface#position */ ve.ce.Surface.prototype.onWindowResize = function () { this.emit( 'position' ); @@ -4144,6 +4153,8 @@ ve.ce.Surface.prototype.onWindowResize = function () { /** * Start a relocation action. + * + * @fires ve.ce.Surface#relocationStart */ ve.ce.Surface.prototype.startRelocation = function () { // Cache the selection and selectedNode when the drag starts, to @@ -4155,6 +4166,8 @@ ve.ce.Surface.prototype.startRelocation = function () { /** * Complete a relocation action. + * + * @fires ve.ce.Surface#relocationEnd */ ve.ce.Surface.prototype.endRelocation = function () { this.relocatingSelection = null; @@ -4928,6 +4941,7 @@ ve.ce.Surface.prototype.showSelectionState = function ( selection ) { * * @param {boolean|Node} [fromModelOrNode] If `true`, gather annotations from the model, * instead of the cusor focus point. If a Node is passed, gather annotations from that node. + * @fires ve.dm.Surface#contextChange */ ve.ce.Surface.prototype.updateActiveAnnotations = function ( fromModelOrNode ) { var activeAnnotations, diff --git a/src/ce/ve.ce.View.js b/src/ce/ve.ce.View.js index 7ceb751fc..8812477a2 100644 --- a/src/ce/ve.ce.View.js +++ b/src/ce/ve.ce.View.js @@ -49,11 +49,11 @@ OO.mixinClass( ve.ce.View, OO.EventEmitter ); /* Events */ /** - * @event setup + * @event ve.ce.View#setup */ /** - * @event teardown + * @event ve.ce.View#teardown */ /* Static members */ @@ -72,6 +72,7 @@ OO.mixinClass( ve.ce.View, OO.EventEmitter ); * @static * @property {boolean|Function} * @param {string} attribute + * @return {boolean} Attibute is allowed * @inheritable */ ve.ce.View.static.renderHtmlAttributes = function ( attribute ) { @@ -158,8 +159,8 @@ ve.ce.View.prototype.isLive = function () { * Set live state. * * @param {boolean} live The view has been attached to the live DOM (use false on detach) - * @fires setup - * @fires teardown + * @fires ve.ce.View#setup + * @fires ve.ce.View#teardown */ ve.ce.View.prototype.setLive = function ( live ) { this.live = live; diff --git a/src/ce/ve.ce.js b/src/ce/ve.ce.js index 71d1eb90d..837150de5 100644 --- a/src/ce/ve.ce.js +++ b/src/ce/ve.ce.js @@ -7,8 +7,7 @@ /** * Namespace for all VisualEditor ContentEditable classes, static methods and static properties. * - * @class - * @singleton + * @namespace */ ve.ce = { // nodeFactory: Initialized in ve.ce.NodeFactory.js diff --git a/src/dm/nodes/ve.dm.GeneratedContentNode.js b/src/dm/nodes/ve.dm.GeneratedContentNode.js index 6bdda3b1a..600a5bc28 100644 --- a/src/dm/nodes/ve.dm.GeneratedContentNode.js +++ b/src/dm/nodes/ve.dm.GeneratedContentNode.js @@ -22,7 +22,7 @@ OO.initClass( ve.dm.GeneratedContentNode ); /* Events */ /** - * @event generatedContentsError + * @event ve.dm.GeneratedContentNode#generatedContentsError * @param {jQuery} $element Element containing the error message */ diff --git a/src/dm/nodes/ve.dm.ImageNode.js b/src/dm/nodes/ve.dm.ImageNode.js index 3a334a38b..634316b9a 100644 --- a/src/dm/nodes/ve.dm.ImageNode.js +++ b/src/dm/nodes/ve.dm.ImageNode.js @@ -28,16 +28,18 @@ OO.mixinClass( ve.dm.ImageNode, ve.dm.ResizableNode ); /* Static Methods */ +// eslint-disable-next-line jsdoc/require-param, jsdoc/require-returns /** - * @inheritdoc ve.dm.Model + * @see ve.dm.Model */ ve.dm.ImageNode.static.isDiffComparable = function ( element, other ) { // Images with different src's shouldn't be diffed return element.type === other.type && element.attributes.src === other.attributes.src; }; +// eslint-disable-next-line jsdoc/require-param, jsdoc/require-returns /** - * @inheritdoc ve.dm.Model + * @see ve.dm.Model */ ve.dm.ImageNode.static.describeChanges = function ( attributeChanges, attributes ) { var customKeys = [ 'width', 'height' ], @@ -70,8 +72,9 @@ ve.dm.ImageNode.static.describeChanges = function ( attributeChanges, attributes return descriptions; }; +// eslint-disable-next-line jsdoc/require-param, jsdoc/require-returns /** - * @inheritdoc ve.dm.Node + * @see ve.dm.Node */ ve.dm.ImageNode.static.describeChange = function ( key, change ) { switch ( key ) { diff --git a/src/dm/nodes/ve.dm.TableNode.js b/src/dm/nodes/ve.dm.TableNode.js index be7cfb777..03162493e 100644 --- a/src/dm/nodes/ve.dm.TableNode.js +++ b/src/dm/nodes/ve.dm.TableNode.js @@ -30,7 +30,7 @@ ve.dm.TableNode = function VeDmTableNode() { OO.inheritClass( ve.dm.TableNode, ve.dm.BranchNode ); /** - * @event cellAttributeChange + * @event ve.dm.TableNode#cellAttributeChange * @param {ve.dm.TableCellableNode} cell */ @@ -61,7 +61,7 @@ ve.dm.TableNode.prototype.onSplice = function () { * Handle cell attribute changes * * @param {ve.dm.TableCellableNode} cell - * @fires cellAttributeChange + * @fires ve.dm.TableNode#cellAttributeChange */ ve.dm.TableNode.prototype.onCellAttributeChange = function ( cell ) { this.emit( 'cellAttributeChange', cell ); @@ -144,12 +144,12 @@ OO.mixinClass( ve.dm.TableNodeCellIterator, OO.EventEmitter ); /* Events */ /** - * @event newSection + * @event ve.dm.TableNodeCellIterator#newSection * @param {ve.dm.TableSectionNode} node Table section node */ /** - * @event newRow + * @event ve.dm.TableNodeCellIterator#newRow * @param {ve.dm.TableRowNode} node Table row node */ @@ -181,7 +181,7 @@ ve.dm.TableNodeCellIterator.prototype.next = function () { /** * Move to the next table section * - * @fires newSection + * @fires ve.dm.TableNodeCellIterator#newSection */ ve.dm.TableNodeCellIterator.prototype.nextSection = function () { // If there are no sections left, finish @@ -207,7 +207,7 @@ ve.dm.TableNodeCellIterator.prototype.nextSection = function () { /** * Move to the next table row * - * @fires newRow + * @fires ve.dm.TableNodeCellIterator#newRow */ ve.dm.TableNodeCellIterator.prototype.nextRow = function () { // If there are no rows left, go to the next section diff --git a/src/dm/nodes/ve.dm.TableRowNode.js b/src/dm/nodes/ve.dm.TableRowNode.js index ca617432d..f8b5cb08b 100644 --- a/src/dm/nodes/ve.dm.TableRowNode.js +++ b/src/dm/nodes/ve.dm.TableRowNode.js @@ -26,11 +26,6 @@ ve.dm.TableRowNode = function VeDmTableRowNode() { OO.inheritClass( ve.dm.TableRowNode, ve.dm.BranchNode ); -/** - * @event cellAttributeChange - * @param {ve.dm.TableCellableNode} cell - */ - /* Static Properties */ ve.dm.TableRowNode.static.name = 'tableRow'; @@ -88,7 +83,7 @@ ve.dm.TableRowNode.prototype.onSplice = function () { * Handle cell attribute changes * * @param {ve.dm.TableCellableNode} cell - * @fires cellAttributeChange + * @fires ve.dm.TableNode#cellAttributeChange */ ve.dm.TableRowNode.prototype.onCellAttributeChange = function ( cell ) { this.emit( 'cellAttributeChange', cell ); diff --git a/src/dm/nodes/ve.dm.TableSectionNode.js b/src/dm/nodes/ve.dm.TableSectionNode.js index aadf3e53f..8a2e95d3d 100644 --- a/src/dm/nodes/ve.dm.TableSectionNode.js +++ b/src/dm/nodes/ve.dm.TableSectionNode.js @@ -26,11 +26,6 @@ ve.dm.TableSectionNode = function VeDmTableSectionNode() { OO.inheritClass( ve.dm.TableSectionNode, ve.dm.BranchNode ); -/** - * @event cellAttributeChange - * @param {ve.dm.TableCellableNode} cell - */ - /* Static Properties */ ve.dm.TableSectionNode.static.name = 'tableSection'; @@ -86,7 +81,7 @@ ve.dm.TableSectionNode.prototype.onSplice = function () { * Handle cell attribute changes * * @param {ve.dm.TableCellableNode} cell - * @fires cellAttributeChange + * @fires ve.dm.TableNode#cellAttributeChange */ ve.dm.TableSectionNode.prototype.onCellAttributeChange = function ( cell ) { this.emit( 'cellAttributeChange', cell ); diff --git a/src/dm/selections/ve.dm.TableSelection.js b/src/dm/selections/ve.dm.TableSelection.js index 84ca0d841..5325c87ec 100644 --- a/src/dm/selections/ve.dm.TableSelection.js +++ b/src/dm/selections/ve.dm.TableSelection.js @@ -215,11 +215,10 @@ ve.dm.TableSelection.prototype.getRanges = function ( doc ) { /** * @inheritdoc - * - * Note that this returns the table range, and not the minimal range covering - * all cells, as that would be far more expensive to compute. */ ve.dm.TableSelection.prototype.getCoveringRange = function () { + // Note that this returns the table range, and not the minimal range covering + // all cells, as that would be far more expensive to compute. return this.tableRange; }; diff --git a/src/dm/ve.dm.BranchNode.js b/src/dm/ve.dm.BranchNode.js index ea7e44b3d..b2aacbb5e 100644 --- a/src/dm/ve.dm.BranchNode.js +++ b/src/dm/ve.dm.BranchNode.js @@ -34,17 +34,13 @@ ve.dm.BranchNode = function VeDmBranchNode( element, children ) { }; /** - * @event splice + * @event ve.dm.BranchNode#splice * @see #method-splice * @param {number} index * @param {number} howmany * @param {ve.dm.BranchNode} [childModel] */ -/** - * @event update - */ - /* Inheritance */ OO.inheritClass( ve.dm.BranchNode, ve.dm.Node ); @@ -58,8 +54,6 @@ OO.mixinClass( ve.dm.BranchNode, ve.BranchNode ); * * @param {ve.dm.BranchNode} childModel Item to add * @return {number} New number of children - * @fires splice - * @fires update */ ve.dm.BranchNode.prototype.push = function ( childModel ) { this.splice( this.children.length, 0, childModel ); @@ -69,9 +63,7 @@ ve.dm.BranchNode.prototype.push = function ( childModel ) { /** * Remove a child node from the end of the list. * - * @return {ve.dm.BranchNode} Removed childModel - * @fires splice - * @fires update + * @return {ve.dm.BranchNode|undefined} Removed childModel */ ve.dm.BranchNode.prototype.pop = function () { if ( this.children.length ) { @@ -86,8 +78,6 @@ ve.dm.BranchNode.prototype.pop = function () { * * @param {ve.dm.BranchNode} childModel Item to add * @return {number} New number of children - * @fires splice - * @fires update */ ve.dm.BranchNode.prototype.unshift = function ( childModel ) { this.splice( 0, 0, childModel ); @@ -97,9 +87,7 @@ ve.dm.BranchNode.prototype.unshift = function ( childModel ) { /** * Remove a child node from the beginning of the list. * - * @return {ve.dm.BranchNode} Removed childModel - * @fires splice - * @fires update + * @return {ve.dm.BranchNode|undefined} Removed childModel */ ve.dm.BranchNode.prototype.shift = function () { if ( this.children.length ) { @@ -115,7 +103,7 @@ ve.dm.BranchNode.prototype.shift = function () { * @param {number} index Index to remove and or insert nodes at * @param {number} howmany Number of nodes to remove * @param {...ve.dm.BranchNode} [nodes] Variadic list of nodes to insert - * @fires splice + * @fires ve.dm.BranchNode#splice * @return {ve.dm.BranchNode[]} Removed nodes */ ve.dm.BranchNode.prototype.splice = function () { diff --git a/src/dm/ve.dm.ClassAttributeNode.js b/src/dm/ve.dm.ClassAttributeNode.js index 09f6bb69e..aa622f151 100644 --- a/src/dm/ve.dm.ClassAttributeNode.js +++ b/src/dm/ve.dm.ClassAttributeNode.js @@ -106,8 +106,9 @@ ve.dm.ClassAttributeNode.static.getClassAttrFromAttributes = function ( attribut return null; }; +// eslint-disable-next-line jsdoc/require-param /** - * @inheritdoc ve.dm.Node + * @see ve.dm.Node */ ve.dm.ClassAttributeNode.static.sanitize = function ( dataElement ) { if ( dataElement.attributes ) { diff --git a/src/dm/ve.dm.Converter.js b/src/dm/ve.dm.Converter.js index 2fe384e23..284657299 100644 --- a/src/dm/ve.dm.Converter.js +++ b/src/dm/ve.dm.Converter.js @@ -1188,7 +1188,7 @@ ve.dm.Converter.prototype.getDataFromDomSubtree = function ( domElement, wrapper * Get inner whitespace from linear data * * @param {ve.dm.ElementLinearData} data Linear model data - * @return {(string|undefined)[]} + * @return {Array.} Sparse array of whitespace strings: [ innerLeft, innerRight ] */ ve.dm.Converter.prototype.getInnerWhitespace = function ( data ) { var innerWhitespace = new Array( 2 ), @@ -1293,7 +1293,7 @@ ve.dm.Converter.prototype.getDomSubtreeFromModel = function ( model, container, * * @param {Array} data Linear model data * @param {HTMLElement} container DOM element to add the generated elements to. Should be empty. - * @param {(string|undefined)[]} [innerWhitespace] Inner whitespace if the container is the body + * @param {Array.} [innerWhitespace] Inner whitespace if the container is the body * @throws Unbalanced data: looking for closing /type */ ve.dm.Converter.prototype.getDomSubtreeFromData = function ( data, container, innerWhitespace ) { diff --git a/src/dm/ve.dm.Document.js b/src/dm/ve.dm.Document.js index 72f353228..d771f7258 100644 --- a/src/dm/ve.dm.Document.js +++ b/src/dm/ve.dm.Document.js @@ -21,7 +21,7 @@ * ignored. * @param {ve.dm.Document} [parentDocument] Document to use as root for created nodes, used when cloning * @param {ve.dm.InternalList} [internalList] Internal list to clone; passed when creating a document slice - * @param {(string|undefined)[]} [innerWhitespace] Inner whitespace to clone; passed when creating a document slice + * @param {Array.} [innerWhitespace] Inner whitespace to clone; passed when creating a document slice * @param {string} [lang] Language code * @param {string} [dir='ltr'] Directionality (ltr/rtl) * @param {ve.dm.Document} [originalDocument] Original document form which this was cloned. @@ -92,17 +92,25 @@ OO.inheritClass( ve.dm.Document, ve.Document ); /* Events */ /** - * @event precommit * Emitted when a transaction is about to be committed. + * + * @event ve.dm.Document#precommit * @param {ve.dm.Transaction} tx Transaction that is about to be committed */ /** - * @event transact * Emitted when a transaction has been committed. + * + * @event ve.dm.Document#transact * @param {ve.dm.Transaction} tx Transaction that was just processed */ +/** + * A value in persistent storage has changed + * + * @event ve.dm.Document#storage + */ + /* Static methods */ /** @@ -372,8 +380,8 @@ ve.dm.Document.prototype.isReadOnly = function () { * * @param {ve.dm.Transaction} transaction Transaction to apply * @param {boolean} isStaging Transaction is being applied in staging mode - * @fires precommit - * @fires transact + * @fires ve.dm.Document#precommit + * @fires ve.dm.Document#transact * @throws {Error} Cannot commit a transaction that has already been committed */ ve.dm.Document.prototype.commit = function ( transaction, isStaging ) { @@ -468,7 +476,7 @@ ve.dm.Document.prototype.getInternalList = function () { /** * Get the document's inner whitespace * - * @return {(string|undefined)[]} The document's inner whitespace + * @return {Array.} The document's inner whitespace */ ve.dm.Document.prototype.getInnerWhitespace = function () { return this.innerWhitespace; @@ -1766,7 +1774,7 @@ ve.dm.Document.prototype.getDir = function () { * * @param {string|Object} [keyOrStorage] Key, or storage object to restore * @param {Mixed} [value] Serializable value, if key is set - * @fires storage + * @fires ve.dm.Document#storage */ ve.dm.Document.prototype.setStorage = function ( keyOrStorage, value ) { if ( typeof keyOrStorage === 'string' ) { diff --git a/src/dm/ve.dm.InternalList.js b/src/dm/ve.dm.InternalList.js index 796a558e5..5e848a1de 100644 --- a/src/dm/ve.dm.InternalList.js +++ b/src/dm/ve.dm.InternalList.js @@ -37,7 +37,7 @@ OO.mixinClass( ve.dm.InternalList, OO.EventEmitter ); /* Events */ /** - * @event update + * @event ve.dm.InternalList#update * @param {string[]} groupsChanged List of groups changed since the last transaction */ @@ -355,7 +355,7 @@ ve.dm.InternalList.prototype.markGroupAsChanged = function ( groupName ) { /** * Handle document transaction events * - * @fires update + * @fires ve.dm.InternalList#update */ ve.dm.InternalList.prototype.onTransact = function () { if ( this.groupsChanged.length > 0 ) { diff --git a/src/dm/ve.dm.MetaList.js b/src/dm/ve.dm.MetaList.js index b4adc41f9..75a6d12fc 100644 --- a/src/dm/ve.dm.MetaList.js +++ b/src/dm/ve.dm.MetaList.js @@ -37,12 +37,12 @@ OO.mixinClass( ve.dm.MetaList, OO.EventEmitter ); /* Events */ /** - * @event insert + * @event ve.dm.MetaList#insert * @param {ve.dm.MetaItem} item Item that was inserted */ /** - * @event remove + * @event ve.dm.MetaList#remove * @param {ve.dm.MetaItem} item Item that was removed */ diff --git a/src/dm/ve.dm.Model.js b/src/dm/ve.dm.Model.js index 4c1a915e6..b9f05b514 100644 --- a/src/dm/ve.dm.Model.js +++ b/src/dm/ve.dm.Model.js @@ -52,7 +52,7 @@ ve.dm.Model.static.matchTagNames = null; * For more information about element matching, see ve.dm.ModelRegistry. * * @static - * @property {(string|RegExp)[]|null} + * @property {Array.|null} * @inheritable */ ve.dm.Model.static.matchRdfaTypes = null; @@ -64,7 +64,7 @@ ve.dm.Model.static.matchRdfaTypes = null; * For more information about element matching, see ve.dm.ModelRegistry. * * @static - * @property {(string|RegExp)[]|null} + * @property {Array.|null} * @inheritable */ ve.dm.Model.static.allowedRdfaTypes = []; @@ -228,7 +228,7 @@ ve.dm.Model.static.getHashObject = function ( dataElement ) { * Array of RDFa types that this model should be a match candidate for. * * @static - * @return {(string|RegExp)[]|null} Array of strings or regular expressions + * @return {Array.|null} Array of strings or regular expressions */ ve.dm.Model.static.getMatchRdfaTypes = function () { return this.matchRdfaTypes; @@ -238,7 +238,7 @@ ve.dm.Model.static.getMatchRdfaTypes = function () { * Extra RDFa types that the element is allowed to have. * * @static - * @return {(string|RegExp)[]|null} Array of strings or regular expressions + * @return {Array.|null} Array of strings or regular expressions */ ve.dm.Model.static.getAllowedRdfaTypes = function () { return this.allowedRdfaTypes; @@ -293,6 +293,7 @@ ve.dm.Model.static.describeChange = function ( key, change ) { return ve.htmlMsg( 'visualeditor-changedesc-changed', key, this.wrapText( 'del', change.from ), this.wrapText( 'ins', change.to ) ); } } + return null; }; /** diff --git a/src/dm/ve.dm.Node.js b/src/dm/ve.dm.Node.js index 20d7396d9..b55b36498 100644 --- a/src/dm/ve.dm.Node.js +++ b/src/dm/ve.dm.Node.js @@ -30,20 +30,19 @@ ve.dm.Node = function VeDmNode( element ) { }; /** - * @event attributeChange + * @event ve.dm.Node#attributeChange * @param {string} key * @param {Mixed} oldValue * @param {Mixed} newValue */ /** - * @event lengthChange + * @event ve.dm.Node#lengthChange * @param {number} diff */ /** - * @event update - * @param {boolean} staged Transaction was applied in staging mode + * @event ve.dm.Node#update */ /* Inheritance */ @@ -444,127 +443,145 @@ ve.dm.Node.prototype.getClonedElement = function ( preserveGenerated, resetAttri return this.constructor.static.cloneElement( this.element, store, preserveGenerated, resetAttributes ); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.getChildNodeTypes = function () { return this.constructor.static.childNodeTypes; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.getParentNodeTypes = function () { return this.constructor.static.parentNodeTypes; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.getSuggestedParentNodeTypes = function () { return this.constructor.static.suggestedParentNodeTypes; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.canHaveChildren = function () { return ve.dm.nodeFactory.canNodeHaveChildren( this.type ); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.canHaveChildrenNotContent = function () { return ve.dm.nodeFactory.canNodeHaveChildrenNotContent( this.type ); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.isInternal = function () { return this.constructor.static.isInternal; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.isMetaData = function () { return this.constructor.static.isMetaData; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.isWrapped = function () { return this.constructor.static.isWrapped; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.isUnwrappable = function () { return this.isWrapped() && this.constructor.static.isUnwrappable; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.canContainContent = function () { return this.constructor.static.canContainContent; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.isContent = function () { return this.constructor.static.isContent; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.isFocusable = function () { return this.constructor.static.isFocusable; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.isAlignable = function () { return this.constructor.static.isAlignable; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.isCellable = function () { return this.constructor.static.isCellable; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.isCellEditable = function () { return this.constructor.static.isCellEditable; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.isDiffedAsList = function () { return this.constructor.static.isDiffedAsList; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.isDiffedAsLeaf = function () { return this.constructor.static.isDiffedAsLeaf; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.isDiffedAsDocument = function () { return this.getChildNodeTypes() === null; @@ -600,22 +617,25 @@ ve.dm.Node.prototype.suppressSlugType = function () { return null; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.hasSignificantWhitespace = function () { return this.constructor.static.hasSignificantWhitespace; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.handlesOwnChildren = function () { return this.constructor.static.handlesOwnChildren; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.shouldIgnoreChildren = function () { return this.constructor.static.ignoreChildren; @@ -687,8 +707,9 @@ ve.dm.Node.prototype.compareAttributes = function ( attributes ) { return true; }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.getLength = function () { return this.length; @@ -701,8 +722,8 @@ ve.dm.Node.prototype.getLength = function () { * not change the document data. * * @param {number} length Length of content - * @fires lengthChange - * @fires update + * @fires ve.dm.Node#lengthChange + * @fires ve.dm.Node#update * @throws {Error} Invalid content length error if length is less than 0 */ ve.dm.Node.prototype.setLength = function ( length ) { @@ -729,16 +750,15 @@ ve.dm.Node.prototype.setLength = function ( length ) { * not change the document data. * * @param {number} adjustment Amount to adjust length by - * @fires lengthChange - * @fires update * @throws {Error} Invalid adjustment error if resulting length is less than 0 */ ve.dm.Node.prototype.adjustLength = function ( adjustment ) { this.setLength( this.length + adjustment ); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.Node + * @see ve.Node */ ve.dm.Node.prototype.getOffset = function () { if ( !this.parent ) { diff --git a/src/dm/ve.dm.Scalable.js b/src/dm/ve.dm.Scalable.js index d9707f195..9dd270788 100644 --- a/src/dm/ve.dm.Scalable.js +++ b/src/dm/ve.dm.Scalable.js @@ -78,35 +78,35 @@ OO.mixinClass( ve.dm.Scalable, OO.EventEmitter ); /** * Current changed * - * @event currentSizeChange + * @event ve.dm.Scalable#currentSizeChange * @param {Object} currentDimensions Current dimensions width and height */ /** * Default size or state changed * - * @event defaultSizeChange + * @event ve.dm.Scalable#defaultSizeChange * @param {boolean} isDefault The size is default */ /** * Original size changed * - * @event originalSizeChange + * @event ve.dm.Scalable#originalSizeChange * @param {Object} originalDimensions Original dimensions width and height */ /** * Min size changed * - * @event minSizeChange + * @event ve.dm.Scalable#minSizeChange * @param {Object} minDimensions Min dimensions width and height */ /** * Max size changed * - * @event maxSizeChange + * @event ve.dm.Scalable#maxSizeChange * @param {Object} maxDimensions Max dimensions width and height */ @@ -225,7 +225,7 @@ ve.dm.Scalable.prototype.setRatioFromDimensions = function ( dimensions ) { * Also sets the aspect ratio if not set and in fixed ratio mode. * * @param {Object} dimensions Dimensions object with width & height - * @fires currentSizeChange + * @fires ve.dm.Scalable#currentSizeChange */ ve.dm.Scalable.prototype.setCurrentDimensions = function ( dimensions ) { if ( @@ -248,7 +248,7 @@ ve.dm.Scalable.prototype.setCurrentDimensions = function ( dimensions ) { * Also resets the aspect ratio if in fixed ratio mode. * * @param {Object} dimensions Dimensions object with width & height - * @fires originalSizeChange + * @fires ve.dm.Scalable#originalSizeChange */ ve.dm.Scalable.prototype.setOriginalDimensions = function ( dimensions ) { if ( @@ -269,7 +269,7 @@ ve.dm.Scalable.prototype.setOriginalDimensions = function ( dimensions ) { * Set the default dimensions * * @param {Object} dimensions Dimensions object with width & height - * @fires defaultSizeChange + * @fires ve.dm.Scalable#defaultSizeChange */ ve.dm.Scalable.prototype.setDefaultDimensions = function ( dimensions ) { if ( @@ -285,7 +285,7 @@ ve.dm.Scalable.prototype.setDefaultDimensions = function ( dimensions ) { /** * Reset and remove the default dimensions * - * @fires defaultSizeChange + * @fires ve.dm.Scalable#defaultSizeChange */ ve.dm.Scalable.prototype.clearDefaultDimensions = function () { if ( this.defaultDimensions !== null ) { @@ -298,7 +298,7 @@ ve.dm.Scalable.prototype.clearDefaultDimensions = function () { /** * Reset and remove the default dimensions * - * @fires originalSizeChange + * @fires ve.dm.Scalable#originalSizeChange */ ve.dm.Scalable.prototype.clearOriginalDimensions = function () { if ( this.originalDimensions !== null ) { @@ -312,7 +312,7 @@ ve.dm.Scalable.prototype.clearOriginalDimensions = function () { * Toggle the default size setting, or set it to particular value * * @param {boolean} [isDefault] Default or not, toggles if unset - * @fires defaultSizeChange + * @fires ve.dm.Scalable#defaultSizeChange */ ve.dm.Scalable.prototype.toggleDefault = function ( isDefault ) { if ( isDefault === undefined ) { @@ -333,7 +333,7 @@ ve.dm.Scalable.prototype.toggleDefault = function ( isDefault ) { * Set the minimum dimensions * * @param {Object} dimensions Dimensions object with width & height - * @fires minSizeChange + * @fires ve.dm.Scalable#minSizeChange */ ve.dm.Scalable.prototype.setMinDimensions = function ( dimensions ) { if ( @@ -350,7 +350,7 @@ ve.dm.Scalable.prototype.setMinDimensions = function ( dimensions ) { * Set the maximum dimensions * * @param {Object} dimensions Dimensions object with width & height - * @fires maxSizeChange + * @fires ve.dm.Scalable#maxSizeChange */ ve.dm.Scalable.prototype.setMaxDimensions = function ( dimensions ) { if ( @@ -366,7 +366,7 @@ ve.dm.Scalable.prototype.setMaxDimensions = function ( dimensions ) { /** * Clear the minimum dimensions * - * @fires minSizeChange + * @fires ve.dm.Scalable#minSizeChange */ ve.dm.Scalable.prototype.clearMinDimensions = function () { if ( this.minDimensions !== null ) { @@ -379,7 +379,7 @@ ve.dm.Scalable.prototype.clearMinDimensions = function () { /** * Clear the maximum dimensions * - * @fires maxSizeChange + * @fires ve.dm.Scalable#maxSizeChange */ ve.dm.Scalable.prototype.clearMaxDimensions = function () { if ( this.maxDimensions !== null ) { diff --git a/src/dm/ve.dm.Surface.js b/src/dm/ve.dm.Surface.js index 5e1400b52..dc1bc928f 100644 --- a/src/dm/ve.dm.Surface.js +++ b/src/dm/ve.dm.Surface.js @@ -87,54 +87,56 @@ OO.mixinClass( ve.dm.Surface, OO.EventEmitter ); /* Events */ /** - * @event select + * @event ve.dm.Surface#select * @param {ve.dm.Selection} selection */ /** - * @event focus - * * The selection was just set to a non-null selection + * + * @event ve.dm.Surface#focus */ /** - * @event blur - * * The selection was just set to a null selection + * + * @event ve.dm.Surface#blur */ /** - * @event documentUpdate - * * Emitted when a transaction has been processed on the document and the selection has been * translated to account for that transaction. You should only use this event if you need * to access the selection; in most cases, you should use {ve.dm.Document#event-transact}. * + * @event ve.dm.Surface#documentUpdate * @param {ve.dm.Transaction} tx Transaction that was processed on the document */ /** - * @event contextChange + * @event ve.dm.Surface#contextChange */ /** - * @event insertionAnnotationsChange + * @event ve.dm.Surface#insertionAnnotationsChange * @param {ve.dm.AnnotationSet} insertionAnnotations AnnotationSet being inserted */ /** - * @event history * Emitted when the history stacks change, or the ability to use them changes. + * + * @event ve.dm.Surface#history */ /** - * @event undoStackChange * Emitted when the main undo stack changes (this.undoStack or this.undoIndex). + * + * @event ve.dm.Surface#undoStackChange */ /** - * @event autosaveFailed * Auto-save failed to store a change + * + * @event ve.dm.Surface#autosaveFailed */ /* Methods */ @@ -169,7 +171,7 @@ ve.dm.Surface.prototype.isReadOnly = function () { /** * Initialize the surface model * - * @fires contextChange + * @fires ve.dm.Surface#contextChange */ ve.dm.Surface.prototype.initialize = function () { this.startHistoryTracking(); @@ -330,6 +332,7 @@ ve.dm.Surface.prototype.getStagingTransactions = function () { * Push another level of staging to the staging stack * * @param {boolean} [allowUndo=false] Allow undo while staging + * @fires ve.dm.Surface#history */ ve.dm.Surface.prototype.pushStaging = function ( allowUndo ) { // If we're starting staging stop history tracking @@ -354,7 +357,7 @@ ve.dm.Surface.prototype.pushStaging = function ( allowUndo ) { /** * Pop a level of staging from the staging stack * - * @fires history + * @fires ve.dm.Surface#history * @return {ve.dm.Transaction[]|undefined} Staging transactions, or undefined if not staging */ ve.dm.Surface.prototype.popStaging = function () { @@ -387,7 +390,7 @@ ve.dm.Surface.prototype.popStaging = function () { /** * Apply a level of staging from the staging stack * - * @fires history + * @fires ve.dm.Surface#history */ ve.dm.Surface.prototype.applyStaging = function () { if ( !this.isStaging() ) { @@ -459,8 +462,8 @@ ve.dm.Surface.prototype.getInsertionAnnotations = function () { * Set annotations that will be used upon insertion. * * @param {ve.dm.AnnotationSet|null} annotations Insertion annotations to use or null to disable them - * @fires insertionAnnotationsChange - * @fires contextChange + * @fires ve.dm.Surface#insertionAnnotationsChange + * @fires ve.dm.Surface#contextChange */ ve.dm.Surface.prototype.setInsertionAnnotations = function ( annotations ) { if ( this.readOnly ) { @@ -478,8 +481,8 @@ ve.dm.Surface.prototype.setInsertionAnnotations = function ( annotations ) { * Add an annotation to be used upon insertion. * * @param {ve.dm.Annotation|ve.dm.AnnotationSet} annotations Insertion annotation to add - * @fires insertionAnnotationsChange - * @fires contextChange + * @fires ve.dm.Surface#insertionAnnotationsChange + * @fires ve.dm.Surface#contextChange */ ve.dm.Surface.prototype.addInsertionAnnotations = function ( annotations ) { if ( this.readOnly ) { @@ -501,8 +504,8 @@ ve.dm.Surface.prototype.addInsertionAnnotations = function ( annotations ) { * Remove an annotation from those that will be used upon insertion. * * @param {ve.dm.Annotation|ve.dm.AnnotationSet} annotations Insertion annotation to remove - * @fires insertionAnnotationsChange - * @fires contextChange + * @fires ve.dm.Surface#insertionAnnotationsChange + * @fires ve.dm.Surface#contextChange */ ve.dm.Surface.prototype.removeInsertionAnnotations = function ( annotations ) { if ( this.readOnly ) { @@ -618,7 +621,7 @@ ve.dm.Surface.prototype.getLinearFragment = function ( range, noAutoSelect, excl * * Callers should eventually emit a 'history' event after using this method. * - * @fires undoStackChange + * @fires ve.dm.Surface#undoStackChange */ ve.dm.Surface.prototype.truncateUndoStack = function () { if ( this.undoIndex ) { @@ -653,7 +656,7 @@ ve.dm.Surface.prototype.startQueueingContextChanges = function () { * is deferred until #stopQueueingContextChanges is called. * * @private - * @fires contextChange + * @fires ve.dm.Surface#contextChange */ ve.dm.Surface.prototype.emitContextChange = function () { if ( this.queueingContextChanges ) { @@ -669,7 +672,7 @@ ve.dm.Surface.prototype.emitContextChange = function () { * event immediately. * * @private - * @fires contextChange + * @fires ve.dm.Surface#contextChange */ ve.dm.Surface.prototype.stopQueueingContextChanges = function () { if ( this.queueingContextChanges ) { @@ -751,8 +754,9 @@ ve.dm.Surface.prototype.fixupRangeForLinks = function ( range ) { * * @param {ve.dm.Selection} selection New selection * - * @fires select - * @fires contextChange + * @fires ve.dm.Surface#select + * @fires ve.dm.Surface#focus + * @fires ve.dm.Surface#blur */ ve.dm.Surface.prototype.setSelection = function ( selection ) { var oldSelection = this.selection; @@ -918,7 +922,6 @@ ve.dm.Surface.prototype.setSelection = function ( selection ) { * @param {ve.dm.Transaction|ve.dm.Transaction[]|null} transactions One or more transactions to * process, or null to process none * @param {ve.dm.Selection} [selection] Selection to apply - * @fires contextChange */ ve.dm.Surface.prototype.change = function ( transactions, selection ) { this.changeInternal( transactions, selection, false ); @@ -931,9 +934,8 @@ ve.dm.Surface.prototype.change = function ( transactions, selection ) { * @param {ve.dm.Transaction|ve.dm.Transaction[]|null} transactions * @param {ve.dm.Selection} [selection] * @param {boolean} [skipUndoStack=false] If true, do not modify the undo stack. Used by undo/redo - * @fires select - * @fires history - * @fires contextChange + * @fires ve.dm.Surface#select + * @fires ve.dm.Surface#history */ ve.dm.Surface.prototype.changeInternal = function ( transactions, selection, skipUndoStack ) { var selectionBefore = this.selection, @@ -1014,7 +1016,7 @@ ve.dm.Surface.prototype.changeInternal = function ( transactions, selection, ski * Set a history state breakpoint. * * @return {boolean} A breakpoint was added - * @fires undoStackChange + * @fires ve.dm.Surface#undoStackChange */ ve.dm.Surface.prototype.breakpoint = function () { if ( this.readOnly ) { @@ -1041,7 +1043,8 @@ ve.dm.Surface.prototype.breakpoint = function () { /** * Step backwards in history. * - * @fires undoStackChange + * @fires ve.dm.Surface#undoStackChange + * @fires ve.dm.Surface#history */ ve.dm.Surface.prototype.undo = function () { if ( !this.canUndo() ) { @@ -1114,7 +1117,7 @@ ve.dm.Surface.prototype.undo = function () { /** * Step forwards in history. * - * @fires undoStackChange + * @fires ve.dm.Surface#undoStackChange */ ve.dm.Surface.prototype.redo = function () { if ( !this.canRedo() ) { @@ -1137,7 +1140,7 @@ ve.dm.Surface.prototype.redo = function () { * other state. * * @param {ve.dm.Transaction} tx Transaction that was processed - * @fires documentUpdate + * @fires ve.dm.Surface#documentUpdate */ ve.dm.Surface.prototype.onDocumentTransact = function ( tx ) { this.setSelection( this.getSelection().translateByTransactionWithAuthor( tx, this.authorId ) ); @@ -1332,6 +1335,8 @@ ve.dm.Surface.prototype.setAuthorId = function ( authorId ) { /** * Store latest transactions into session storage + * + * @fires ve.dm.Surface#autosaveFailed */ ve.dm.Surface.prototype.storeChanges = function () { if ( this.autosaveFailed ) { diff --git a/src/dm/ve.dm.SurfaceSynchronizer.js b/src/dm/ve.dm.SurfaceSynchronizer.js index ab41ba769..578c78603 100644 --- a/src/dm/ve.dm.SurfaceSynchronizer.js +++ b/src/dm/ve.dm.SurfaceSynchronizer.js @@ -126,31 +126,32 @@ OO.mixinClass( ve.dm.SurfaceSynchronizer, ve.dm.RebaseClient ); /* Events */ /** - * @event authorSelect + * @event ve.dm.SurfaceSynchronizer#authorSelect * @param {number} authorId The author whose selection has changed */ /** - * @event authorChange + * @event ve.dm.SurfaceSynchronizer#authorChange * @param {number} authorId The author whose data has changed */ /** - * @event wrongDoc + * @event ve.dm.SurfaceSynchronizer#wrongDoc */ /** - * @event initDoc + * @event ve.dm.SurfaceSynchronizer#initDoc * @param {Error} error Error, if there was a problem initializing the document */ /** - * @event disconnect + * @event ve.dm.SurfaceSynchronizer#disconnect */ /** - * @event pause * The synchronizer is paused or resumes + * + * @event ve.dm.SurfaceSynchronizer#pause */ /* Methods */ @@ -167,6 +168,8 @@ ve.dm.SurfaceSynchronizer.prototype.destroy = function () { /** * Pause sending/receiving changes + * + * @fires ve.dm.SurfaceSynchronizer#pause */ ve.dm.SurfaceSynchronizer.prototype.pauseChanges = function () { if ( this.paused ) { @@ -179,6 +182,8 @@ ve.dm.SurfaceSynchronizer.prototype.pauseChanges = function () { /** * Resume sending/receiving changes + * + * @fires ve.dm.SurfaceSynchronizer#pause */ ve.dm.SurfaceSynchronizer.prototype.resumeChanges = function () { if ( !this.paused ) { @@ -330,7 +335,7 @@ ve.dm.SurfaceSynchronizer.prototype.onSurfaceSelect = function () { * * @param {Object} newSelections Each author (key) maps to a new incoming ve.dm.Selection * @param {ve.dm.Change|ve.dm.Transaction} [changeOrTx] Object to translate over, if any - * @fires authorSelect + * @fires ve.dm.SurfaceSynchronizer#authorSelect */ ve.dm.SurfaceSynchronizer.prototype.applyNewSelections = function ( newSelections, changeOrTx ) { var change = changeOrTx instanceof ve.dm.Change ? changeOrTx : null, @@ -394,7 +399,7 @@ ve.dm.SurfaceSynchronizer.prototype.onAuthorDisconnect = function ( authorId ) { * @param {Object} data * @param {number} data.authorId The author ID allocated by the server * @param {string} data.token - * @fires wrongDoc + * @fires ve.dm.SurfaceSynchronizer#wrongDoc */ ve.dm.SurfaceSynchronizer.prototype.onRegistered = function ( data ) { if ( this.serverId && this.serverId !== data.serverId ) { @@ -433,7 +438,7 @@ ve.dm.SurfaceSynchronizer.prototype.loadSessionKey = function () { * @param {Object} data * @param {Object} data.history Serialized change representing the server's history * @param {Object} data.authors Object mapping author IDs to author data objects (name/color) - * @fires initDoc + * @fires ve.dm.SurfaceSynchronizer#initDoc */ ve.dm.SurfaceSynchronizer.prototype.onInitDoc = function ( data ) { if ( this.initialized ) { diff --git a/src/dm/ve.dm.TableMatrix.js b/src/dm/ve.dm.TableMatrix.js index 44dfc481f..ad404331d 100644 --- a/src/dm/ve.dm.TableMatrix.js +++ b/src/dm/ve.dm.TableMatrix.js @@ -49,7 +49,7 @@ ve.dm.TableMatrix = function VeDmTableMatrix( tableNode ) { OO.mixinClass( ve.dm.TableMatrix, OO.EventEmitter ); /** - * @event structureChange + * @event ve.dm.TableMatrix#structureChange */ /** @@ -57,7 +57,7 @@ OO.mixinClass( ve.dm.TableMatrix, OO.EventEmitter ); * * This is called by ve.dm.TableNode on structural changes. * - * @fires structureChange + * @fires ve.dm.TableMatrix#structureChange */ ve.dm.TableMatrix.prototype.invalidate = function () { this.matrix = null; diff --git a/src/dm/ve.dm.Transaction.js b/src/dm/ve.dm.Transaction.js index 1a55bb23c..a7e863603 100644 --- a/src/dm/ve.dm.Transaction.js +++ b/src/dm/ve.dm.Transaction.js @@ -55,7 +55,7 @@ OO.initClass( ve.dm.Transaction ); * If a property's treatment isn't specified, its value is simply copied without modification. * If an operation type's treatment isn't specified, all properties are copied without modification. * - * @type {Object.>>} + * @type {Object.} */ ve.dm.Transaction.static.reversers = { attribute: { from: 'to', to: 'from' }, // Swap .from with .to diff --git a/src/dm/ve.dm.VisualDiff.js b/src/dm/ve.dm.VisualDiff.js index 4cc4ef9ae..3c6473a1e 100644 --- a/src/dm/ve.dm.VisualDiff.js +++ b/src/dm/ve.dm.VisualDiff.js @@ -274,7 +274,7 @@ ve.dm.VisualDiff.prototype.diffList = function ( oldNodes, newNodes ) { * unchanged nodes, or objects where the `node` property is the index for changed nodes. * @param {Object.} newToOld Map of newDoc nodes to corresponding oldDoc nodes. * Same format at oldToNew. - * @return {(number|string)[]} Record of whether and how each newDoc node has moved + * @return {Array.} Record of whether and how each newDoc node has moved (0, 'up', 'down') */ ve.dm.VisualDiff.prototype.calculateDiffMoves = function ( oldToNew, newToOld ) { var oldPermuted = [], diff --git a/src/dm/ve.dm.js b/src/dm/ve.dm.js index 9061eaf96..46208cbe5 100644 --- a/src/dm/ve.dm.js +++ b/src/dm/ve.dm.js @@ -7,8 +7,7 @@ /** * Namespace for all VisualEditor DataModel classes, static methods and static properties. * - * @class - * @singleton + * @namespace */ ve.dm = { // modelRegistry: Initialized in ve.dm.ModelRegistry.js diff --git a/src/init/sa/ve.init.sa.Target.js b/src/init/sa/ve.init.sa.Target.js index ec659d8ef..23cdf191a 100644 --- a/src/init/sa/ve.init.sa.Target.js +++ b/src/init/sa/ve.init.sa.Target.js @@ -48,7 +48,7 @@ OO.inheritClass( ve.init.sa.Target, ve.init.Target ); /** * @inheritdoc - * @fires surfaceReady + * @fires ve.init.Target#surfaceReady */ ve.init.sa.Target.prototype.addSurface = function () { // Parent method diff --git a/src/init/sa/ve.init.sa.js b/src/init/sa/ve.init.sa.js index 3f3561640..2ce83d976 100644 --- a/src/init/sa/ve.init.sa.js +++ b/src/init/sa/ve.init.sa.js @@ -8,8 +8,7 @@ * Namespace for all VisualEditor stand-alone Initialization classes, static methods and static * properties. * - * @class - * @singleton + * @namespace */ ve.init.sa = { }; diff --git a/src/init/ve.init.SupportCheck.js b/src/init/ve.init.SupportCheck.js index 3c139479b..42a844bda 100644 --- a/src/init/ve.init.SupportCheck.js +++ b/src/init/ve.init.SupportCheck.js @@ -12,7 +12,7 @@ * use this to check for feature compatibility this file must be ES3-parsable. * * @method VisualEditorSupportCheck - * @member global + * @memberof ve * @return {boolean} True if the environment should support VisualEditor. */ window.VisualEditorSupportCheck = function () { diff --git a/src/init/ve.init.Target.js b/src/init/ve.init.Target.js index becab1971..e814ec4f3 100644 --- a/src/init/ve.init.Target.js +++ b/src/init/ve.init.Target.js @@ -82,9 +82,9 @@ OO.mixinClass( ve.init.Target, OO.EventEmitter ); /* Events */ /** - * @event surfaceReady - * * Must be fired after the surface is initialized + * + * @event ve.init.Target#surfaceReady */ /* Static Properties */ @@ -184,14 +184,14 @@ ve.init.Target.static.actionGroups = []; /** * List of commands which can be triggered anywhere from within the document * - * @type {string[]} List of command names + * @type {string[]} */ ve.init.Target.static.documentCommands = []; /** * List of commands which can be triggered from within the target element * - * @type {string[]} List of command names + * @type {string[]} */ ve.init.Target.static.targetCommands = [ 'commandHelp', 'findAndReplace', 'findNext', 'findPrevious' ]; @@ -200,14 +200,14 @@ ve.init.Target.static.targetCommands = [ 'commandHelp', 'findAndReplace', 'findN * * Null means all commands in the registry are used (excluding excludeCommands) * - * @type {string[]|null} List of command names + * @type {string[]|null} */ ve.init.Target.static.includeCommands = null; /** * List of commands to exclude from the target entirely * - * @type {string[]} List of command names + * @type {string[]} */ ve.init.Target.static.excludeCommands = []; diff --git a/src/init/ve.init.js b/src/init/ve.init.js index c83c7ae97..bf0a7ee6f 100644 --- a/src/init/ve.init.js +++ b/src/init/ve.init.js @@ -7,8 +7,7 @@ /** * Namespace for all VisualEditor Initialization classes, static methods and static properties. * - * @class - * @singleton + * @namespace */ ve.init = { // platform: Initialized in a file containing a subclass of ve.init.Platform diff --git a/src/ui/actions/ve.ui.CompletionAction.js b/src/ui/actions/ve.ui.CompletionAction.js index 9131a90ff..656b34acc 100644 --- a/src/ui/actions/ve.ui.CompletionAction.js +++ b/src/ui/actions/ve.ui.CompletionAction.js @@ -30,29 +30,26 @@ OO.inheritClass( ve.ui.CompletionAction, ve.ui.Action ); /* Static Properties */ /** - * Length to which to limit the list of returned completions + * @property {number} Length to which to limit the list of returned completions * * @static - * @property {number} */ ve.ui.CompletionAction.static.defaultLimit = 8; /** - * Length of the sequence which triggers the action + * @property {number} Length of the trigger sequence for the action * * This many characters will be stripped from the start of the current input by * CompletionWidget when triggered by a sequence, see #getSequenceLength. * * @static - * @property {number} */ ve.ui.CompletionAction.static.sequenceLength = 1; /** - * Whether the current input should be included as a completion automatically + * @property {boolean} Whether the current input should be included as a completion automatically * * @static - * @property {boolean} */ ve.ui.CompletionAction.static.alwaysIncludeInput = true; diff --git a/src/ui/actions/ve.ui.FormatAction.js b/src/ui/actions/ve.ui.FormatAction.js index 59f80d273..a097de75c 100644 --- a/src/ui/actions/ve.ui.FormatAction.js +++ b/src/ui/actions/ve.ui.FormatAction.js @@ -48,7 +48,7 @@ ve.ui.FormatAction.prototype.convert = function ( type, attributes ) { fragmentSelection = fragment.getSelection(); if ( !( fragmentSelection instanceof ve.dm.LinearSelection ) ) { - return; + return false; } var fragments = []; diff --git a/src/ui/actions/ve.ui.LinkAction.js b/src/ui/actions/ve.ui.LinkAction.js index c64811735..d1176f6f7 100644 --- a/src/ui/actions/ve.ui.LinkAction.js +++ b/src/ui/actions/ve.ui.LinkAction.js @@ -28,9 +28,8 @@ OO.inheritClass( ve.ui.LinkAction, ve.ui.Action ); ve.ui.LinkAction.static.name = 'link'; /** - * RegExp matching an autolink + trailing space. + * @property {RegExp} RegExp matching an autolink + trailing space. * - * @property {RegExp} * @private */ ve.ui.LinkAction.static.autolinkRegExp = null; // Initialized below. diff --git a/src/ui/contextitems/ve.ui.LinearContextItem.js b/src/ui/contextitems/ve.ui.LinearContextItem.js index bcdeb5169..eccdce255 100644 --- a/src/ui/contextitems/ve.ui.LinearContextItem.js +++ b/src/ui/contextitems/ve.ui.LinearContextItem.js @@ -90,12 +90,6 @@ ve.ui.LinearContextItem = function VeUiLinearContextItem( context, model, config OO.inheritClass( ve.ui.LinearContextItem, ve.ui.ContextItem ); OO.mixinClass( ve.ui.ContextItem, OO.ui.mixin.PendingElement ); -/* Events */ - -/** - * @event command - */ - /* Static Properties */ ve.ui.LinearContextItem.static.editable = true; @@ -118,6 +112,7 @@ ve.ui.LinearContextItem.static.embeddable = true; * @localdoc Executes the command related to #static-commandName on the context's surface * * @protected + * @fires ve.ui.ContextItem#command */ ve.ui.LinearContextItem.prototype.onEditButtonClick = function () { var command = this.getCommand(); diff --git a/src/ui/contextitems/ve.ui.MobileActionsContextItem.js b/src/ui/contextitems/ve.ui.MobileActionsContextItem.js index 56796550d..e7bd85c34 100644 --- a/src/ui/contextitems/ve.ui.MobileActionsContextItem.js +++ b/src/ui/contextitems/ve.ui.MobileActionsContextItem.js @@ -102,6 +102,8 @@ ve.ui.MobileActionsContextItem.prototype.onCopyButtonClick = function () { /** * Handle delete button click events. + * + * @fires ve.ui.ContextItem#command */ ve.ui.MobileActionsContextItem.prototype.onDeleteButtonClick = function () { var surface = this.context.getSurface(); diff --git a/src/ui/contextitems/ve.ui.TableLineContextItem.js b/src/ui/contextitems/ve.ui.TableLineContextItem.js index 1e487511f..727b6d993 100644 --- a/src/ui/contextitems/ve.ui.TableLineContextItem.js +++ b/src/ui/contextitems/ve.ui.TableLineContextItem.js @@ -58,6 +58,7 @@ ve.ui.TableLineContextItem.static.title = null; * @localdoc Executes the command related to #static-commandName on the context's surface * * @protected + * @fires ve.ui.ContextItem#command */ ve.ui.TableLineContextItem.prototype.onActionButtonClick = function () { var command = this.getCommand(); diff --git a/src/ui/contexts/ve.ui.LinearContext.js b/src/ui/contexts/ve.ui.LinearContext.js index 9fb0d1df1..cd7021781 100644 --- a/src/ui/contexts/ve.ui.LinearContext.js +++ b/src/ui/contexts/ve.ui.LinearContext.js @@ -233,9 +233,7 @@ ve.ui.LinearContext.prototype.removePersistentSource = function ( name ) { }; /** - * @inheritdoc - * - * Also adds the `embeddable` property to each object. + * @inheritdoc Also adds the `embeddable` property to each object. */ ve.ui.LinearContext.prototype.getRelatedSources = function () { var surfaceModel = this.surface.getModel(), diff --git a/src/ui/dialogs/ve.ui.FragmentDialog.js b/src/ui/dialogs/ve.ui.FragmentDialog.js index 2d8f86a59..0715e52c3 100644 --- a/src/ui/dialogs/ve.ui.FragmentDialog.js +++ b/src/ui/dialogs/ve.ui.FragmentDialog.js @@ -68,7 +68,7 @@ ve.ui.FragmentDialog.prototype.initialize = function ( data ) { }; /** - * @inheritdoc OO.ui.Dialog + * @inheritdoc */ ve.ui.FragmentDialog.prototype.getActionWidgetConfig = function ( config ) { // Mixin method diff --git a/src/ui/dialogs/ve.ui.ToolbarDialog.js b/src/ui/dialogs/ve.ui.ToolbarDialog.js index 8e23f010e..f2661685c 100644 --- a/src/ui/dialogs/ve.ui.ToolbarDialog.js +++ b/src/ui/dialogs/ve.ui.ToolbarDialog.js @@ -42,7 +42,7 @@ ve.ui.ToolbarDialog.static.padded = true; * For 'inline' the caller will be manually positioning the dialog. * * @static - * @type {string} Toolbar position + * @type {string} */ ve.ui.ToolbarDialog.static.position = 'above'; diff --git a/src/ui/elements/ve.ui.DiffElement.js b/src/ui/elements/ve.ui.DiffElement.js index 293d9c903..98bac6d98 100644 --- a/src/ui/elements/ve.ui.DiffElement.js +++ b/src/ui/elements/ve.ui.DiffElement.js @@ -191,7 +191,7 @@ ve.ui.DiffElement.prototype.positionDescriptions = function () { * Process a diff queue, skipping over sequential nodes with no changes * * @param {Array[]} queue Diff queue - * @return {(Array|null)[]} + * @return {Array.} */ ve.ui.DiffElement.prototype.processQueue = function processQueue( queue ) { var hasChanges = false, @@ -278,7 +278,7 @@ ve.ui.DiffElement.prototype.processQueue = function processQueue( queue ) { }; /** - * @param {(Array|null)[]} queue Diff queue + * @param {Array.} queue Diff queue * @param {HTMLElement} parentNode Parent node to render to * @param {HTMLElement} spacerNode Spacer node template */ diff --git a/src/ui/elements/ve.ui.PreviewElement.js b/src/ui/elements/ve.ui.PreviewElement.js index e594fb29c..fc5083f31 100644 --- a/src/ui/elements/ve.ui.PreviewElement.js +++ b/src/ui/elements/ve.ui.PreviewElement.js @@ -40,7 +40,7 @@ ve.ui.PreviewElement = function VeUiPreviewElement( model, config ) { /** * The element rendering has been updated * - * @event render + * @event ve.ui.PreviewElement#render */ /* Inheritance */ @@ -144,7 +144,7 @@ ve.ui.PreviewElement.prototype.updatePreview = function () { /** * Cleanup and emit events after render * - * @fires render + * @fires ve.ui.PreviewElement#render */ ve.ui.PreviewElement.prototype.afterRender = function () { // Cleanup diff --git a/src/ui/inspectors/ve.ui.AnnotationInspector.js b/src/ui/inspectors/ve.ui.AnnotationInspector.js index 885b7f0f3..4b50ee68b 100644 --- a/src/ui/inspectors/ve.ui.AnnotationInspector.js +++ b/src/ui/inspectors/ve.ui.AnnotationInspector.js @@ -123,8 +123,9 @@ ve.ui.AnnotationInspector.prototype.getMatchingAnnotations = function ( fragment } ); }; +// eslint-disable-next-line jsdoc/require-returns /** - * @inheritdoc ve.ui.FragmentWindow + * @see ve.ui.FragmentWindow */ ve.ui.AnnotationInspector.prototype.isEditing = function () { // If initialSelection isn't set yet, default to assume we are editing, diff --git a/src/ui/inspectors/ve.ui.FragmentInspector.js b/src/ui/inspectors/ve.ui.FragmentInspector.js index 02836037c..9dfdb374d 100644 --- a/src/ui/inspectors/ve.ui.FragmentInspector.js +++ b/src/ui/inspectors/ve.ui.FragmentInspector.js @@ -117,7 +117,7 @@ ve.ui.FragmentInspector.prototype.getActionProcess = function ( action ) { }; /** - * @inheritdoc OO.ui.Dialog + * @inheritdoc */ ve.ui.FragmentInspector.prototype.getActionWidgetConfig = function ( config ) { // Mixin method diff --git a/src/ui/ve.ui.Action.js b/src/ui/ve.ui.Action.js index 5b7030125..5c12c9b29 100644 --- a/src/ui/ve.ui.Action.js +++ b/src/ui/ve.ui.Action.js @@ -30,7 +30,7 @@ OO.initClass( ve.ui.Action ); /* Static Properties */ /** - * List of allowed methods for the action. + * @property {string[]} List of allowed methods for the action. * * To avoid use of methods not intended to be executed via surface.execute(), the allowed methods * must be listed here. This information is checked by ve.ui.Surface before executing an action. @@ -42,7 +42,6 @@ OO.initClass( ve.ui.Action ); * be carried out. * * @static - * @property {string[]} * @inheritable */ ve.ui.Action.static.methods = []; diff --git a/src/ui/ve.ui.Context.js b/src/ui/ve.ui.Context.js index 3e2b38963..3d0c876e4 100644 --- a/src/ui/ve.ui.Context.js +++ b/src/ui/ve.ui.Context.js @@ -56,7 +56,7 @@ OO.mixinClass( ve.ui.Context, OO.ui.mixin.GroupElement ); /* Events */ /** - * @event resize + * @event ve.ui.Context#resize */ /* Static Properties */ @@ -224,7 +224,7 @@ ve.ui.Context.prototype.onContextItemCommand = function () {}; * * @param {boolean} [show] Show the context, omit to toggle * @return {jQuery.Promise} Promise resolved when context is finished showing/hiding - * @fires resize + * @fires ve.ui.Context#resize */ ve.ui.Context.prototype.toggle = function ( show ) { show = show === undefined ? !this.visible : !!show; @@ -241,7 +241,7 @@ ve.ui.Context.prototype.toggle = function ( show ) { * * @return {ve.ui.Context} * @chainable - * @fires resize + * @fires ve.ui.Context#resize */ ve.ui.Context.prototype.updateDimensions = function () { // Override in subclass if context is positioned relative to content diff --git a/src/ui/ve.ui.ContextItem.js b/src/ui/ve.ui.ContextItem.js index f91353746..a1583f078 100644 --- a/src/ui/ve.ui.ContextItem.js +++ b/src/ui/ve.ui.ContextItem.js @@ -50,7 +50,9 @@ OO.inheritClass( ve.ui.ContextItem, OO.ui.Widget ); /* Events */ /** - * @event command + * The context executed a ve.ui.Command + * + * @event ve.ui.ContextItem#command */ /* Static Properties */ diff --git a/src/ui/ve.ui.FragmentWindow.js b/src/ui/ve.ui.FragmentWindow.js index 7c62125c9..a4eb7aee5 100644 --- a/src/ui/ve.ui.FragmentWindow.js +++ b/src/ui/ve.ui.FragmentWindow.js @@ -34,8 +34,9 @@ ve.ui.FragmentWindow.prototype.getFragment = function () { return this.fragment; }; +// eslint-disable-next-line jsdoc/require-param, jsdoc/require-returns /** - * @inheritdoc OO.ui.Dialog + * @see OO.ui.Dialog */ ve.ui.FragmentWindow.prototype.getActionWidgetConfig = function ( config ) { if ( config.action === 'done' && OO.ui.isMobile() ) { @@ -48,8 +49,9 @@ ve.ui.FragmentWindow.prototype.getActionWidgetConfig = function ( config ) { return config; }; +// eslint-disable-next-line jsdoc/require-param, jsdoc/require-returns /** - * @inheritdoc OO.ui.Window + * @see OO.ui.Window * @throws {Error} If fragment was not provided through data parameter */ ve.ui.FragmentWindow.prototype.getSetupProcess = function ( data, process ) { @@ -72,8 +74,9 @@ ve.ui.FragmentWindow.prototype.getSetupProcess = function ( data, process ) { }, this ); }; +// eslint-disable-next-line jsdoc/require-param, jsdoc/require-returns /** - * @inheritdoc OO.ui.Window + * @see OO.ui.Window */ ve.ui.FragmentWindow.prototype.getTeardownProcess = function ( data, process ) { ve.track( 'activity.' + this.constructor.static.name, { action: 'dialog-' + ( data && data.action || 'abort' ) } ); diff --git a/src/ui/ve.ui.NodeWindow.js b/src/ui/ve.ui.NodeWindow.js index 8ac344571..3ed0413e2 100644 --- a/src/ui/ve.ui.NodeWindow.js +++ b/src/ui/ve.ui.NodeWindow.js @@ -74,9 +74,6 @@ ve.ui.NodeWindow.prototype.getSelectedNode = function () { return null; }; -/** - * @inheritdoc OO.ui.Window - */ ve.ui.NodeWindow.prototype.getSetupProcess = function ( data, process ) { data = data || {}; return process.next( function () { @@ -84,9 +81,6 @@ ve.ui.NodeWindow.prototype.getSetupProcess = function ( data, process ) { }, this ); }; -/** - * @inheritdoc OO.ui.Window - */ ve.ui.NodeWindow.prototype.getTeardownProcess = function ( data, process ) { data = data || {}; return process.next( function () { diff --git a/src/ui/ve.ui.PositionedTargetToolbar.js b/src/ui/ve.ui.PositionedTargetToolbar.js index 59279253b..c8df5fe32 100644 --- a/src/ui/ve.ui.PositionedTargetToolbar.js +++ b/src/ui/ve.ui.PositionedTargetToolbar.js @@ -83,11 +83,11 @@ ve.ui.PositionedTargetToolbar.prototype.detach = function () { }; /** - * @inheritdoc - * * While toolbar floating is enabled, * the toolbar will stick to the top of the screen unless it would be over or under the last visible * branch node in the root of the document being edited, at which point it will stop just above it. + * + * @inheritdoc */ ve.ui.PositionedTargetToolbar.prototype.onWindowResize = function () { ve.ui.Toolbar.super.prototype.onWindowResize.call( this ); diff --git a/src/ui/ve.ui.SequenceRegistry.js b/src/ui/ve.ui.SequenceRegistry.js index b8041e037..567d5200f 100644 --- a/src/ui/ve.ui.SequenceRegistry.js +++ b/src/ui/ve.ui.SequenceRegistry.js @@ -37,6 +37,14 @@ ve.ui.SequenceRegistry.prototype.register = function ( sequence ) { ve.ui.SequenceRegistry.super.prototype.register.call( this, sequence.getName(), sequence ); }; +/** + * Matching sequence and corresponding range + * + * @type {Object} Match + * @property {ve.ui.Sequence} sequence + * @property {ve.Range} range + */ + /** * Find sequence matches a given offset in the data * @@ -44,9 +52,7 @@ ve.ui.SequenceRegistry.prototype.register = function ( sequence ) { * @param {number} offset * @param {boolean} [isPaste] Whether this in the context of a paste * @param {boolean} [isDelete] Whether this is after content being deleted - * @return {{sequence:ve.ui.Sequence,range:ve.Range}[]} - * Array of matching sequences, and the corresponding range of the match - * for each. + * @return {Match[]} Array of matching sequences, and the corresponding range of the match for each. */ ve.ui.SequenceRegistry.prototype.findMatching = function ( data, offset, isPaste, isDelete ) { // To avoid blowup when matching RegExp sequences, we're going to grab diff --git a/src/ui/ve.ui.Surface.js b/src/ui/ve.ui.Surface.js index 5e30272b7..fe9745070 100644 --- a/src/ui/ve.ui.Surface.js +++ b/src/ui/ve.ui.Surface.js @@ -159,38 +159,38 @@ OO.inheritClass( ve.ui.Surface, OO.ui.Widget ); /** * When a surface has been initialized * - * @event ready + * @event ve.ui.Surface#ready */ /** * When a surface is destroyed. * - * @event destroy + * @event ve.ui.Surface#destroy */ /** * The surface was scrolled programmatically * as a result of a native selection change * - * @event scroll + * @event ve.ui.Surface#scroll */ /** * The surface has been submitted by user action, e.g. Ctrl+Enter * - * @event submit + * @event ve.ui.Surface#submit */ /** * The surface has been cancelled by user action, e.g. Escape * - * @event cancel + * @event ve.ui.Surface#cancel */ /** * The surface read-only state has changed * - * @event readOnly + * @event ve.ui.Surface#readOnly * @param {boolean} readOnly The surface is read-only */ @@ -201,7 +201,7 @@ OO.inheritClass( ve.ui.Surface, OO.ui.Widget ); * * @return {ve.ui.Surface} * @chainable - * @fires destroy + * @fires ve.ui.Surface#destroy */ ve.ui.Surface.prototype.destroy = function () { // Destroy the ce.Surface, the ui.Context and window managers @@ -234,6 +234,7 @@ ve.ui.Surface.prototype.destroy = function () { * * @return {ve.ui.Surface} * @chainable + * @fires ve.ui.Surface#ready */ ve.ui.Surface.prototype.initialize = function () { $( OO.ui.getTeleportTarget() ).append( this.globalOverlay.$element ); @@ -458,6 +459,7 @@ ve.ui.Surface.prototype.setDisabled = function ( disabled ) { * Set the read-only state of the surface * * @param {boolean} readOnly Make surface read-only + * @fires ve.ui.Surface#readOnly */ ve.ui.Surface.prototype.setReadOnly = function ( readOnly ) { this.readOnly = !!readOnly; @@ -523,7 +525,7 @@ ve.ui.Surface.prototype.onModelSelect = function () { * * @param {ve.dm.Selection} [selectionModel] Optional selection model, defaults to current selection * @param {Object} [scrollConfig] Scroll config options, passed to ve.scrollIntoView - * @fires scroll + * @fires ve.ui.Surface#scroll */ ve.ui.Surface.prototype.scrollSelectionIntoView = function ( selectionModel, scrollConfig ) { selectionModel = selectionModel || this.getModel().getSelection(); diff --git a/src/ui/ve.ui.Toolbar.js b/src/ui/ve.ui.Toolbar.js index 9eded799a..dfdbc1f07 100644 --- a/src/ui/ve.ui.Toolbar.js +++ b/src/ui/ve.ui.Toolbar.js @@ -42,20 +42,20 @@ OO.inheritClass( ve.ui.Toolbar, OO.ui.Toolbar ); /* Events */ /** - * @event updateState + * @event ve.ui.Toolbar#updateState * @param {ve.dm.SurfaceFragment|null} fragment Surface fragment. Null if no surface is active. * @param {Object|null} direction Context direction with 'inline' & 'block' properties if a surface exists. Null if no surface is active. * @param {string[]} activeDialogs List of names of currently open dialogs. */ /** - * @event surfaceChange + * @event ve.ui.Toolbar#surfaceChange * @param {ve.ui.Surface|null} oldSurface Old surface being controlled * @param {ve.ui.Surface|null} newSurface New surface being controlled */ /** - * @event resize + * @event ve.ui.Toolbar#resize */ /* Methods */ @@ -65,6 +65,8 @@ OO.inheritClass( ve.ui.Toolbar, OO.ui.Toolbar ); * * @param {Object} groups List of tool group configurations * @param {ve.ui.Surface} [surface] Surface to attach to + * @fires ve.ui.Toolbar#surfaceChange + * @fires ve.ui.Toolbar#resize */ ve.ui.Toolbar.prototype.setup = function ( groups, surface ) { var oldSurface, @@ -160,7 +162,7 @@ ve.ui.Toolbar.prototype.onInspectorOrDialogOpeningOrClosing = function ( win, op /** * Handle context changes on the surface. * - * @fires updateState + * @fires ve.ui.Toolbar#updateState */ ve.ui.Toolbar.prototype.onContextChange = function () { this.updateToolStateDebounced(); @@ -168,6 +170,8 @@ ve.ui.Toolbar.prototype.onContextChange = function () { /** * Update the state of the tools + * + * @fires ve.ui.Toolbar#updateState */ ve.ui.Toolbar.prototype.updateToolState = function () { if ( !this.getSurface() ) { diff --git a/src/ui/ve.ui.Trigger.js b/src/ui/ve.ui.Trigger.js index df1a551ee..003143ec1 100644 --- a/src/ui/ve.ui.Trigger.js +++ b/src/ui/ve.ui.Trigger.js @@ -62,21 +62,17 @@ OO.initClass( ve.ui.Trigger ); /* Static Properties */ /** - * Symbolic modifier key names. - * - * The order of this array affects the canonical order of a trigger string. + * @property {string[]} Symbolic modifier key names. The order of this array affects the canonical order of a trigger string. * * @static - * @property {string[]} * @inheritable */ ve.ui.Trigger.static.modifierKeys = [ 'meta', 'ctrl', 'alt', 'shift' ]; /** - * Symbolic primary key names. + * @property {string[]} Symbolic primary key names. * * @static - * @property {string[]} * @inheritable */ ve.ui.Trigger.static.primaryKeys = [ @@ -169,10 +165,9 @@ ve.ui.Trigger.static.primaryKeys = [ ]; /** - * Mappings to use when rendering string for a specific platform. + * @property {Object} Mappings to use when rendering string for a specific platform. * * @static - * @property {Object} * @inheritable */ ve.ui.Trigger.static.platformMapping = { @@ -201,10 +196,9 @@ ve.ui.Trigger.static.platformMapping = { }; /** - * Symbol to use when concatenating keys in a sequence. + * @property {Object} Symbol to use when concatenating keys in a sequence. * * @static - * @property {Object} * @inheritable */ ve.ui.Trigger.static.platformStringJoiners = { @@ -213,10 +207,9 @@ ve.ui.Trigger.static.platformStringJoiners = { }; /** - * Special keys which have i18n messages + * @property {string[]} Special keys which have i18n messages * * @static - * @property {string[]} * @inheritable */ ve.ui.Trigger.static.translatableKeys = [ @@ -242,10 +235,9 @@ ve.ui.Trigger.static.translatableKeys = [ ]; /** - * Aliases for modifier or primary key names. + * @property {Object} Aliases for modifier or primary key names. * * @static - * @property {Object} * @inheritable */ ve.ui.Trigger.static.keyAliases = { @@ -272,10 +264,9 @@ ve.ui.Trigger.static.keyAliases = { }; /** - * Mapping of key codes and symbolic key names. + * @property {Object} Mapping of key codes and symbolic key names. * * @static - * @property {Object} * @inheritable */ ve.ui.Trigger.static.primaryKeyMap = { diff --git a/src/ui/ve.ui.js b/src/ui/ve.ui.js index 46b15f91b..f019b5ba3 100644 --- a/src/ui/ve.ui.js +++ b/src/ui/ve.ui.js @@ -7,8 +7,7 @@ /** * Namespace for all VisualEditor UserInterface classes, static methods and static properties. * - * @class - * @singleton + * @namespace */ ve.ui = { // 'actionFactory' instantiated in ve.ui.ActionFactory.js diff --git a/src/ui/widgets/ve.ui.DimensionsWidget.js b/src/ui/widgets/ve.ui.DimensionsWidget.js index 3edce8c9a..8429e184f 100644 --- a/src/ui/widgets/ve.ui.DimensionsWidget.js +++ b/src/ui/widgets/ve.ui.DimensionsWidget.js @@ -68,12 +68,12 @@ OO.inheritClass( ve.ui.DimensionsWidget, OO.ui.Widget ); /* Events */ /** - * @event widthChange + * @event ve.ui.DimensionsWidget#widthChange * @param {string} value The new width */ /** - * @event heightChange + * @event ve.ui.DimensionsWidget#heightChange * @param {string} value The new width */ @@ -83,7 +83,7 @@ OO.inheritClass( ve.ui.DimensionsWidget, OO.ui.Widget ); * Respond to width change, propagate the input change event * * @param {string} value The new changed value - * @fires widthChange + * @fires ve.ui.DimensionsWidget#widthChange */ ve.ui.DimensionsWidget.prototype.onWidthChange = function ( value ) { this.emit( 'widthChange', value ); @@ -93,7 +93,7 @@ ve.ui.DimensionsWidget.prototype.onWidthChange = function ( value ) { * Respond to height change, propagate the input change event * * @param {string} value The new changed value - * @fires heightChange + * @fires ve.ui.DimensionsWidget#heightChange */ ve.ui.DimensionsWidget.prototype.onHeightChange = function ( value ) { this.emit( 'heightChange', value ); diff --git a/src/ui/widgets/ve.ui.LanguageInputWidget.js b/src/ui/widgets/ve.ui.LanguageInputWidget.js index 7dc4aa78e..2a04d727c 100644 --- a/src/ui/widgets/ve.ui.LanguageInputWidget.js +++ b/src/ui/widgets/ve.ui.LanguageInputWidget.js @@ -113,7 +113,7 @@ OO.inheritClass( ve.ui.LanguageInputWidget, OO.ui.Widget ); /* Events */ /** - * @event change + * @event ve.ui.LanguageInputWidget#change * @param {string} lang Language code * @param {string} dir Directionality */ @@ -159,7 +159,7 @@ ve.ui.LanguageInputWidget.prototype.onChange = function () { * * @param {string|null} lang Language code * @param {string|null} dir Directionality - * @fires change + * @fires ve.ui.LanguageInputWidget#change * @return {ve.ui.LanguageInputWidget} * @chainable */ diff --git a/src/ui/widgets/ve.ui.LinkAnnotationWidget.js b/src/ui/widgets/ve.ui.LinkAnnotationWidget.js index bf8f942b7..049260f8b 100644 --- a/src/ui/widgets/ve.ui.LinkAnnotationWidget.js +++ b/src/ui/widgets/ve.ui.LinkAnnotationWidget.js @@ -38,10 +38,9 @@ OO.inheritClass( ve.ui.LinkAnnotationWidget, OO.ui.Widget ); /* Events */ /** - * @event change - * * A change event is emitted when the annotation value of the input changes. * + * @event ve.ui.LinkAnnotationWidget#change * @param {ve.dm.LinkAnnotation|null} annotation */ @@ -147,6 +146,7 @@ ve.ui.LinkAnnotationWidget.prototype.onTextChange = function ( value ) { * @param {boolean} [fromText] Annotation was generated from text input * @return {ve.ui.LinkAnnotationWidget} * @chainable + * @fires ve.ui.LinkAnnotationWidget#change */ ve.ui.LinkAnnotationWidget.prototype.setAnnotation = function ( annotation, fromText ) { if ( ve.compare( diff --git a/src/ui/widgets/ve.ui.MediaSizeWidget.js b/src/ui/widgets/ve.ui.MediaSizeWidget.js index 4603cd810..706cba007 100644 --- a/src/ui/widgets/ve.ui.MediaSizeWidget.js +++ b/src/ui/widgets/ve.ui.MediaSizeWidget.js @@ -124,17 +124,17 @@ OO.inheritClass( ve.ui.MediaSizeWidget, OO.ui.Widget ); /* Events */ /** - * @event change + * @event ve.ui.MediaSizeWidget#change * @param {Object} dimensions Width and height dimensions */ /** - * @event valid + * @event ve.ui.MediaSizeWidget#valid * @param {boolean} isValid Current dimensions are valid */ /** - * @event changeSizeType + * @event ve.ui.MediaSizeWidget#changeSizeType * @param {string} sizeType 'default', 'custom' or 'scale' */ @@ -197,7 +197,7 @@ ve.ui.MediaSizeWidget.prototype.onScalableDefaultSizeChange = function ( isDefau * * @param {string} type The input that was updated, 'width' or 'height' * @param {string} value The new value of the input - * @fires change + * @fires ve.ui.MediaSizeWidget#change */ ve.ui.MediaSizeWidget.prototype.onDimensionsChange = function ( type, value ) { if ( +value === 0 && !this.noDefaultDimensions ) { @@ -233,7 +233,7 @@ ve.ui.MediaSizeWidget.prototype.onScaleChange = function () { * Respond to size type change * * @param {OO.ui.OptionWidget} item Selected size type item - * @fires changeSizeType + * @fires ve.ui.MediaSizeWidget#changeSizeType */ ve.ui.MediaSizeWidget.prototype.onSizeTypeChoose = function ( item ) { var selectedType = item.getData(), @@ -463,7 +463,7 @@ ve.ui.MediaSizeWidget.prototype.updateDisabled = function () { * Updates the current dimensions in the inputs, either one at a time or both * * @param {Object} dimensions Dimensions with width and height - * @fires change + * @fires ve.ui.MediaSizeWidget#change */ ve.ui.MediaSizeWidget.prototype.setCurrentDimensions = function ( dimensions ) { // Recursion protection @@ -509,6 +509,7 @@ ve.ui.MediaSizeWidget.prototype.setCurrentDimensions = function ( dimensions ) { * class if needed. * * @return {boolean} Current dimensions are valid + * @fires ve.ui.MediaSizeWidget#valid */ ve.ui.MediaSizeWidget.prototype.validateDimensions = function () { var isValid = this.isValid(); @@ -517,7 +518,7 @@ ve.ui.MediaSizeWidget.prototype.validateDimensions = function () { this.valid = isValid; this.errorLabel.toggle( !isValid ); this.dimensions.setValidityFlag(); - // Emit change event + // Emit validation change event this.emit( 'valid', this.valid ); } return isValid; diff --git a/src/ui/widgets/ve.ui.TargetWidget.js b/src/ui/widgets/ve.ui.TargetWidget.js index 1ced5add3..31cc4245b 100644 --- a/src/ui/widgets/ve.ui.TargetWidget.js +++ b/src/ui/widgets/ve.ui.TargetWidget.js @@ -73,25 +73,25 @@ OO.mixinClass( ve.ui.TargetWidget, OO.ui.mixin.PendingElement ); /** * The target's surface has been changed. * - * @event change + * @event ve.ui.TargetWidget#change */ /** * The target's surface has been submitted, e.g. Ctrl+Enter * - * @event submit + * @event ve.ui.TargetWidget#submit */ /** * The target's surface has been cancelled, e.g. Escape * - * @event cancel + * @event ve.ui.TargetWidget#cancel */ /** * A document has been attached to the target, and a toolbar and surface created. * - * @event setup + * @event ve.ui.TargetWidget#setup */ /** @@ -114,6 +114,9 @@ ve.ui.TargetWidget.prototype.createTarget = function () { * This replaces the entire surface in the target. * * @param {ve.dm.Document} doc + * @fires ve.ui.TargetWidget#change + * @fires ve.ui.TargetWidget#setup + * @fires ve.ce.Surface#position */ ve.ui.TargetWidget.prototype.setDocument = function ( doc ) { // Destroy the previous surface @@ -155,7 +158,7 @@ ve.ui.TargetWidget.prototype.setDocument = function ( doc ) { /** * Handle surface submit events * - * @fires submit + * @fires ve.ui.TargetWidget#submit */ ve.ui.TargetWidget.prototype.onSurfaceSubmit = function () { var handled = this.emit( 'submit' ); @@ -171,7 +174,7 @@ ve.ui.TargetWidget.prototype.onSurfaceSubmit = function () { /** * Handle surface cancel events * - * @fires cancel + * @fires ve.ui.TargetWidget#cancel */ ve.ui.TargetWidget.prototype.onSurfaceCancel = function () { var handled = this.emit( 'cancel' ); diff --git a/src/ve.Document.js b/src/ve.Document.js index 13cdb91a7..69c6635e4 100644 --- a/src/ve.Document.js +++ b/src/ve.Document.js @@ -33,7 +33,7 @@ OO.mixinClass( ve.Document, OO.EventEmitter ); * to be attached too (and the event is emitted for descendants first, and for siblings * in their order in the children list) * - * @event nodeAttached + * @event ve.Document#nodeAttached * @param {ve.Node} node The node that has been attached */ @@ -42,7 +42,7 @@ OO.mixinClass( ve.Document, OO.EventEmitter ); * to be detached too (and the event is emitted for descendants first, and for siblings * in their order in the children list) * - * @event nodeDetached + * @event ve.Document#nodeDetached * @param {ve.Node} node The node that has been detached */ @@ -582,6 +582,7 @@ ve.Document.prototype.rangeInsideOneLeafNode = function ( range ) { * The node and all its children are guaranteed to be attached * * @param {ve.Node} node The node attached + * @fires ve.Document#nodeAttached */ ve.Document.prototype.nodeAttached = function ( node ) { this.emit( 'nodeAttached', node ); @@ -593,6 +594,7 @@ ve.Document.prototype.nodeAttached = function ( node ) { * The node and all its children are guaranteed to be attached * * @param {ve.Node} node The node detached + * @fires ve.Document#nodeDetached */ ve.Document.prototype.nodeDetached = function ( node ) { this.emit( 'nodeDetached', node ); diff --git a/src/ve.EventSequencer.js b/src/ve.EventSequencer.js index 7afd5c5dc..439c1c2b2 100644 --- a/src/ve.EventSequencer.js +++ b/src/ve.EventSequencer.js @@ -137,6 +137,7 @@ ve.EventSequencer.prototype.attach = function ( $node ) { return this; }; +// eslint-disable-next-line jsdoc/require-returns-check /** * Detach from a node (if attached), to stop listen to its jQuery events * diff --git a/src/ve.Node.js b/src/ve.Node.js index b4b2cce94..2c5797eb1 100644 --- a/src/ve.Node.js +++ b/src/ve.Node.js @@ -21,12 +21,12 @@ ve.Node = function VeNode() { }; /** - * @event attach + * @event ve.Node#attach * @param {ve.Node} New parent */ /** - * @event detach + * @event ve.Node#detach * @param {ve.Node} Old parent */ @@ -36,7 +36,7 @@ ve.Node = function VeNode() { * The root will be consistent with that set in descendants and ancestors, but other parts of the * tree may be inconsistent. * - * @event root + * @event ve.Node#root * @param {ve.Node} New root */ @@ -46,7 +46,7 @@ ve.Node = function VeNode() { * The root will be consistent with that set in descendants and ancestors, but other parts of the * tree may be inconsistent. * - * @event unroot + * @event ve.Node#unroot * @param {ve.Node} Old root */ @@ -345,8 +345,8 @@ ve.Node.prototype.getRoot = function () { * This method is overridden by nodes with children. * * @param {ve.Node|null} root Node to use as root - * @fires root - * @fires unroot + * @fires ve.Node#root + * @fires ve.Node#unroot */ ve.Node.prototype.setRoot = function ( root ) { var oldRoot = this.root; @@ -398,7 +398,7 @@ ve.Node.prototype.setDocument = function ( doc ) { * Attach the node to another as a child. * * @param {ve.Node} parent Node to attach to - * @fires attach + * @fires ve.Node#attach */ ve.Node.prototype.attach = function ( parent ) { this.parent = parent; @@ -410,7 +410,7 @@ ve.Node.prototype.attach = function ( parent ) { /** * Detach the node from its parent. * - * @fires detach + * @fires ve.Node#detach */ ve.Node.prototype.detach = function () { var parent = this.parent; diff --git a/src/ve.debug.js b/src/ve.debug.js index 76509f79b..cd16af2ca 100644 --- a/src/ve.debug.js +++ b/src/ve.debug.js @@ -8,16 +8,10 @@ /** * @property {boolean} debug - * @member ve + * @memberof ve */ ve.debug = true; -/** - * @class ve.debug - * @override ve - * @singleton - */ - /* Methods */ /** diff --git a/src/ve.js b/src/ve.js index ab13950b2..1feadb43b 100644 --- a/src/ve.js +++ b/src/ve.js @@ -7,8 +7,7 @@ /** * Namespace for all VisualEditor classes, static methods and static properties. * - * @class ve - * @singleton + * @namespace ve */ window.ve = {}; diff --git a/src/ve.track.js b/src/ve.track.js index ca458ca59..63adf7405 100644 --- a/src/ve.track.js +++ b/src/ve.track.js @@ -17,7 +17,7 @@ * and reliability. VisualEditor does not transmit these events by default, but it provides a * generic interface for routing these events to an analytics framework. * - * @member ve + * @memberof ve * @param {string} topic Event name * @param {Object} [data] Additional data describing the event, encoded as an object */ @@ -33,7 +33,7 @@ * handler was registered, with the topic, event data payload, and event timestamp as the first, * second, and third arguments, respectively. * - * @member ve + * @memberof ve * @param {string} topic Handle events whose name starts with this string prefix * @param {Function} callback Handler to call for each matching tracked event */ diff --git a/src/ve.utils.client.js b/src/ve.utils.client.js index 8e94fde90..daa8969e4 100644 --- a/src/ve.utils.client.js +++ b/src/ve.utils.client.js @@ -6,7 +6,7 @@ /** * @method - * @inheritdoc OO.ui.Element#scrollIntoView + * @see OO.ui.Element#scrollIntoView */ ve.scrollIntoView = OO.ui.Element.static.scrollIntoView.bind( OO.ui.Element.static ); diff --git a/src/ve.utils.js b/src/ve.utils.js index 27c395df0..f1a9fbddd 100644 --- a/src/ve.utils.js +++ b/src/ve.utils.js @@ -4,10 +4,6 @@ * @copyright See AUTHORS.txt */ -/** - * @class ve - */ - /** * Checks if an object is an instance of one or more classes. * @@ -174,13 +170,13 @@ ve.copy = OO.copy; /** * @method - * @inheritdoc OO.ui#debounce + * @see OO.ui#debounce */ ve.debounce = OO.ui.debounce; /** * @method - * @inheritdoc OO.ui#throttle + * @see OO.ui#throttle */ ve.throttle = OO.ui.throttle; diff --git a/src/ve.utils.parsing.js b/src/ve.utils.parsing.js index de8f85a58..aa8e455d9 100644 --- a/src/ve.utils.parsing.js +++ b/src/ve.utils.parsing.js @@ -4,10 +4,6 @@ * @copyright See AUTHORS.txt */ -/** - * @class ve - */ - /** * Check whether a given DOM element has a block element type. *