Fixed documentation errors

Many of these problems were introduced in I859b5871a9d2f17d970c002067c8ff24f3513e9f Change-Id: Ifc2dc4934f782c4ce5107e3a356e357aef754083
2024-11-24 22:35:41 +00:00 · 2013-01-22 14:41:22 -08:00 · 2013-01-22 14:41:22 -08:00 · bf5ba1ea2b
parent 721e69cd9e
commit bf5ba1ea2b
21 changed files with 48 additions and 38 deletions
--- a/.docs/categories.json
+++ b/.docs/categories.json
@ -72,7 +72,7 @@
 		"groups": [
 			{
 				"name": "General",
-				"classes": ["ve.ui", "ve.ui.Context", "ve.ui.Frame", "ve.ui.InspectorFactory", "ve.ui.Menu", "ve.ui.Toolbar"]
+				"classes": ["ve.ui", "ve.ui.Context", "ve.ui.Frame", "ve.ui.InspectorFactory", "ve.ui.Toolbar", "ve.ui.ToolFactory"]
 			},
 			{
 				"name": "Tools",
@ -81,6 +81,10 @@
 			{
 				"name": "Inspectors",
 				"classes": ["ve.ui.*Inspector"]
+			},
+			{
+				"name": "Widgets",
+				"classes": ["ve.ui.*Widget"]
 			}
 		]
 	},
@ -93,11 +97,11 @@
 			},
 			{
 				"name": "Registries",
-				"classes": ["ve.CommandRegistry"]
+				"classes": ["ve.CommandRegistry", "ve.TriggerRegistry"]
 			},
 			{
 				"name": "Factories",
-				"classes": ["ve.ActionFactory", "ve.ToolFactory"]
+				"classes": ["ve.ActionFactory"]
 			},
 			{
 				"name": "Nodes",
--- a/modules/ve/ce/nodes/ve.ce.ListNode.js
+++ b/modules/ve/ce/nodes/ve.ce.ListNode.js
@ -55,7 +55,7 @@ ve.ce.ListNode.prototype.onUpdate = function () {
 * Handle splice events.
 *
 * This is used to solve a rendering bug in Firefox.
- * @see ve.ce.BranchNode.prototype.onSplice
+ * @see ve.ce.BranchNode#onSplice
 *
 * @method
 */
--- a/modules/ve/ce/ve.ce.ContentBranchNode.js
+++ b/modules/ve/ce/ve.ce.ContentBranchNode.js
@ -38,7 +38,7 @@ ve.inheritClass( ve.ce.ContentBranchNode, ve.ce.BranchNode );
 * Handle splice events.
 *
 * This is used to automatically render contents.
- * @see ve.ce.BranchNode.prototype.onSplice
+ * @see ve.ce.BranchNode#onSplice
 *
 * @method
 */
--- a/modules/ve/ce/ve.ce.Surface.js
+++ b/modules/ve/ce/ve.ce.Surface.js
@ -539,7 +539,7 @@ ve.ce.Surface.prototype.onDocumentCompositionEnd = function () {
 /**
 * Handle change events.
 *
- * @see ve.dm.Surface.prototype.change.
+ * @see ve.dm.Surface#change
 *
 * @method
 * @param {ve.dm.Transaction|null} transaction
@ -554,7 +554,7 @@ ve.ce.Surface.prototype.onChange = function ( transaction, selection ) {
 /**
 * Handle selection change events.
 *
- * @see ve.ce.SurfaceObserver.prototype.poll
+ * @see ve.ce.SurfaceObserver#poll
 *
 * @method
 * @param {ve.Range} oldRange
@ -569,7 +569,7 @@ ve.ce.Surface.prototype.onSelectionChange = function ( oldRange, newRange ) {
 /**
 * Handle content change events.
 *
- * @see ve.ce.SurfaceObserver.prototype.poll
+ * @see ve.ce.SurfaceObserver#poll
 *
 * @method
 * @param {HTMLElement} node DOM node the change occured in
--- a/modules/ve/dm/annotations/ve.dm.LinkAnnotation.js
+++ b/modules/ve/dm/annotations/ve.dm.LinkAnnotation.js
@ -8,7 +8,7 @@
 /**
 * DataModel link annotation.
 *
- * Represents <a> tags that don't have a specific type.
+ * Represents `<a>` tags that don't have a specific type.
 *
 * @class
 * @extends ve.dm.Annotation
--- a/modules/ve/dm/ve.dm.Annotation.js
+++ b/modules/ve/dm/ve.dm.Annotation.js
@ -63,7 +63,7 @@ ve.dm.Annotation.static.name = null;
 *
 * Empty array means none, null means any.
 *
- * @see ve#dm#AnnotationFactory
+ * @see ve.dm.AnnotationFactory
 *
 * @static
 * @property {Array} static.matchTagNames
@ -76,7 +76,7 @@ ve.dm.Annotation.static.matchTagNames = null;
 *
 * Empty array means none, null means any.
 *
- * @see ve#dm#AnnotationFactory
+ * @see ve.dm.AnnotationFactory
 *
 * @static
 * @property {Array} static.matchRdfaType
--- a/modules/ve/dm/ve.dm.Document.js
+++ b/modules/ve/dm/ve.dm.Document.js
@ -491,11 +491,11 @@ ve.dm.Document.prototype.getLength = function () {
 /**
 * Splice data into and/or out of the linear model.
 *
- * {@link #metadata} will be updated accordingly.
+ * `this.metadata` will be updated accordingly.
 *
- * Always use this function, never use this.data.splice() directly, otherwise the linear model
- * (this.data) and the meta-linmod (this.metadata) can get out of sync. The semantics of the
- * parameters are identical to those of ve.batchSplice()
+ * Always use this function, never use `this.data.splice()` directly, otherwise the linear model
+ * (`this.data`) and the meta-linmod (`this.metadata`) can get out of sync. The semantics of the
+ * parameters are identical to those of ve#batchSplice
 *
 * @method
 * @see ve#batchSplice
@ -1094,7 +1094,7 @@ ve.dm.Document.prototype.fixupInsertion = function ( data, offset ) {
 	 * This function updates parentNode, parentType, openingStack and closingStack.
 	 *
 	 * @private
-	 * @function
+	 * @method
 	 * @param {Object|Array|string} element Linear model element
 	 * @param {number} index Index in data that the element came from (for error reporting only)
 	 */
--- a/modules/ve/init/mw/targets/ve.init.mw.ViewPageTarget.js
+++ b/modules/ve/init/mw/targets/ve.init.mw.ViewPageTarget.js
@ -1,5 +1,3 @@
-/*global mw, confirm, alert */
-
 /*!
 * VisualEditor MediaWiki Initialization ViewPageTarget class.
 *
@ -7,6 +5,8 @@
 * @license The MIT License (MIT); see LICENSE.txt
 */

+/*global mw, confirm, alert */
+
 /**
 * Initialization MediaWiki view page target.
 *
@ -920,7 +920,7 @@ ve.init.mw.ViewPageTarget.prototype.detachToolbarButtons = function () {
 * Get a template for the save dialog.
 *
 * The result of this function depends on an API call, so the result it provided asynchronously.
- * The template will be wrapped in a plain <div> jQuery collection.
+ * The template will be wrapped in a plain `<div>` jQuery collection.
 *
 * @method
 * @param {Function} callback
--- a/modules/ve/init/mw/ve.init.mw.Platform.js
+++ b/modules/ve/init/mw/ve.init.mw.Platform.js
@ -1,5 +1,3 @@
-/*global mw */
-
 /*!
 * VisualEditor MediaWiki Initialization Target class.
 *
@ -7,6 +5,8 @@
 * @license The MIT License (MIT); see LICENSE.txt
 */

+/*global mw */
+
 /**
 * Initialization MediaWiki platform.
 *
--- a/modules/ve/init/mw/ve.init.mw.Target.js
+++ b/modules/ve/init/mw/ve.init.mw.Target.js
@ -1,5 +1,3 @@
-/*global mw */
-
 /*!
 * VisualEditor MediaWiki Initialization Target class.
 *
@ -7,6 +5,8 @@
 * @license The MIT License (MIT); see LICENSE.txt
 */

+/*global mw */
+
 /**
 * Initialization MediaWiki target.
 *
--- a/modules/ve/ui/inspectors/ve.ui.MWLinkInspector.js
+++ b/modules/ve/ui/inspectors/ve.ui.MWLinkInspector.js
@ -1,5 +1,3 @@
-/*global mw */
-
 /*!
 * VisualEditor user interface LinkInspector class.
 *
@ -7,6 +5,8 @@
 * @license The MIT License (MIT); see LICENSE.txt
 */

+/*global mw */
+
 /**
 * Creates an ve.ui.LinkInspector object.
 *
--- a/modules/ve/ui/styles/ve.ui.Widget.css
+++ b/modules/ve/ui/styles/ve.ui.Widget.css
@ -1,4 +1,4 @@
-/**
+/*!
 * VisualEditor user interface Widget styles.
 *
 * @copyright 2011-2012 VisualEditor Team and others; see AUTHORS.txt
--- a/modules/ve/ui/ve.ui.Context.js
+++ b/modules/ve/ui/ve.ui.Context.js
@ -64,7 +64,7 @@ ve.ui.Context.static = {};
 /**
 * Options for iframe.
 *
- * @see ve#ui#Frame
+ * @see ve.ui.Frame
 *
 * @static
 * @property
--- a/modules/ve/ui/ve.ui.Frame.js
+++ b/modules/ve/ui/ve.ui.Frame.js
@ -59,7 +59,7 @@ ve.ui.Frame.prototype.$$ = function ( selector ) {
 * @private
 * @param {jQuery} $frame Frame to attach and initialize
 * @param {jQuery} $container Container to append frame to
- * @returns {HTMLDocument} Frame document
+ * @returns {HTMLElement} Frame document
 */
 ve.ui.Frame.prototype.attachFrame = function ( $frame, $container ) {
 	var doc;
--- a/modules/ve/ui/ve.ui.Widget.js
+++ b/modules/ve/ui/ve.ui.Widget.js
@ -1,4 +1,4 @@
-/**
+/*!
 * VisualEditor user interface Widget class.
 *
 * @copyright 2011-2012 VisualEditor Team and others; see AUTHORS.txt
--- a/modules/ve/ui/widgets/ve.ui.InputWidget.js
+++ b/modules/ve/ui/widgets/ve.ui.InputWidget.js
@ -1,4 +1,4 @@
-/**
+/*!
 * VisualEditor user interface InputWidget class.
 *
 * @copyright 2011-2012 VisualEditor Team and others; see AUTHORS.txt
@ -47,6 +47,12 @@ ve.ui.InputWidget = function VeUiInputWidget( $$, type, name, value ) {

 ve.inheritClass( ve.ui.InputWidget, ve.ui.Widget );

+/**
+ * @event change
+ * @param value
+ * @param origin
+ */
+
 /* Methods */

 /**
@ -65,7 +71,7 @@ ve.ui.InputWidget.prototype.getValue = function () {
 * @method
 * @param {string} value New value
 * @param {string} [origin] Origin of change
- * @emits change (value, origin)
+ * @emits change
 */
 ve.ui.InputWidget.prototype.setValue = function ( value, origin ) {
 	var domValue = this.$input.val();
--- a/modules/ve/ui/widgets/ve.ui.LinkTargetInputWidget.js
+++ b/modules/ve/ui/widgets/ve.ui.LinkTargetInputWidget.js
@ -1,4 +1,4 @@
-/**
+/*!
 * VisualEditor user interface LinkTargetInputWidget class.
 *
 * @copyright 2011-2012 VisualEditor Team and others; see AUTHORS.txt
--- a/modules/ve/ui/widgets/ve.ui.MWLinkTargetInputWidget.js
+++ b/modules/ve/ui/widgets/ve.ui.MWLinkTargetInputWidget.js
@ -1,11 +1,12 @@
-/*global mw*/
-/**
+/*!
 * VisualEditor user interface MWLinkTargetInputWidget class.
 *
 * @copyright 2011-2012 VisualEditor Team and others; see AUTHORS.txt
 * @license The MIT License (MIT); see LICENSE.txt
 */

+/*global mw*/
+
 /**
 * Creates an ve.ui.MWLinkTargetInputWidget object.
 *
--- a/modules/ve/ui/widgets/ve.ui.MenuWidget.js
+++ b/modules/ve/ui/widgets/ve.ui.MenuWidget.js
@ -167,10 +167,9 @@ ve.ui.MenuWidget.prototype.getItems = function () {
 * Sets the position of the menu.
 *
 * @method
- * @returns {ve.Position} New menu position
 */
 ve.ui.MenuWidget.prototype.setPosition = function ( position ) {
-	return this.$.css( {
+	this.$.css( {
 		'top': position.top,
 		'left': position.left
 	} );
--- a/modules/ve/ui/widgets/ve.ui.TextInputMenuWidget.js
+++ b/modules/ve/ui/widgets/ve.ui.TextInputMenuWidget.js
@ -1,4 +1,4 @@
-/**
+/*!
 * VisualEditor user interface TextInputMenuWidget class.
 *
 * @copyright 2011-2012 VisualEditor Team and others; see AUTHORS.txt
--- a/modules/ve/ui/widgets/ve.ui.TextInputWidget.js
+++ b/modules/ve/ui/widgets/ve.ui.TextInputWidget.js
@ -1,4 +1,4 @@
-/**
+/*!
 * VisualEditor user interface TextInputWidget class.
 *
 * @copyright 2011-2012 VisualEditor Team and others; see AUTHORS.txt