Normalize jsdoc formatting (#1111)

* Normalize jsdoc formatting

src/clone-element.js

@@ -2,10 +2,12 @@ import { extend } from './util';
 import { h } from './h';
 
 /**
- * Clones the given VNode, optionally adding attributes/props and replacing its children.
- * @param {VNode} vnode		The virtual DOM element to clone
- * @param {Object} props	Attributes/props to add when cloning
- * @param {VNode} rest		Any additional arguments will be used as replacement children.
+ * Clones the given VNode, optionally adding attributes/props and replacing its
+ * children.
+ * @param {VNode} vnode The virtual DOM element to clone
+ * @param {Object} props Attributes/props to add when cloning
+ * @param {VNode} rest Any additional arguments will be used as replacement
+ *  children.
  */
 export function cloneElement(vnode, props) {
 	return h(

src/component.js

@@ -2,53 +2,60 @@ import { FORCE_RENDER } from './constants';
 import { extend } from './util';
 import { renderComponent } from './vdom/component';
 import { enqueueRender } from './render-queue';
-
-/** Base Component class.
- *	Provides `setState()` and `forceUpdate()`, which trigger rendering.
- *	@public
+/**
+ * Base Component class.
+ * Provides `setState()` and `forceUpdate()`, which trigger rendering.
+ * @public
  *
- *	@example
- *	class MyFoo extends Component {
- *		render(props, state) {
- *			return <div />;
- *		}
- *	}
+ * @example
+ * class MyFoo extends Component {
+ *   render(props, state) {
+ *     return <div />;
+ *   }
+ * }
  */
 export function Component(props, context) {
 	this._dirty = true;
 
-	/** @public
-	 *	@type {object}
+	/**
+	 * @public
+	 * @type {object}
 	 */
 	this.context = context;
 
-	/** @public
-	 *	@type {object}
+	/**
+	 * @public
+	 * @type {object}
 	 */
 	this.props = props;
 
-	/** @public
-	 *	@type {object}
+	/**
+	 * @public
+	 * @type {object}
 	 */
 	this.state = this.state || {};
 }
 
 
 extend(Component.prototype, {
 
-	/** Returns a `boolean` indicating if the component should re-render when receiving the given `props` and `state`.
-	 *	@param {object} nextProps
-	 *	@param {object} nextState
-	 *	@param {object} nextContext
-	 *	@returns {Boolean} should the component re-render
-	 *	@name shouldComponentUpdate
-	 *	@function
+	/**
+	 * Returns a `boolean` indicating if the component should re-render when
+	 * receiving the given `props` and `state`.
+	 * @param {object} nextProps
+	 * @param {object} nextState
+	 * @param {object} nextContext
+	 * @returns {boolean} should the component re-render
+	 * @name shouldComponentUpdate
+	 * @function
 	 */
 
 
-	/** Update component state by copying properties from `state` to `this.state`.
-	 *	@param {object} state		A hash of state properties to update with new values
-	 *	@param {function} callback	A function to be called once component state is updated
+	/**
+	 * Update component state by copying properties from `state` to `this.state`.
+	 * @param {object} state A hash of state properties to update with new values
+	 * @param {function} callback	A function to be called once component state is
+	 * 	updated
 	 */
 	setState(state, callback) {
 		let s = this.state;
@@ -59,22 +66,27 @@ extend(Component.prototype, {
 	},
 
 
-	/** Immediately perform a synchronous re-render of the component.
-	 *	@param {function} callback		A function to be called after component is re-rendered.
-	 *	@private
+	/**
+	 * Immediately perform a synchronous re-render of the component.
+	 * @param {function} callback	A function to be called after component is
+	 * 	re-rendered.
+	 * @private
 	 */
 	forceUpdate(callback) {
 		if (callback) (this._renderCallbacks = (this._renderCallbacks || [])).push(callback);
 		renderComponent(this, FORCE_RENDER);
 	},
 
 
-	/** Accepts `props` and `state`, and returns a new Virtual DOM tree to build.
-	 *	Virtual DOM is generally constructed via [JSX](http://jasonformat.com/wtf-is-jsx).
-	 *	@param {object} props		Props (eg: JSX attributes) received from parent element/component
-	 *	@param {object} state		The component's current state
-	 *	@param {object} context		Context object (if a parent component has provided context)
-	 *	@returns VNode
+	/**
+	 * Accepts `props` and `state`, and returns a new Virtual DOM tree to build.
+	 * Virtual DOM is generally constructed via [JSX](http://jasonformat.com/wtf-is-jsx).
+	 * @param {object} props Props (eg: JSX attributes) received from parent
+	 * 	element/component
+	 * @param {object} state The component's current state
+	 * @param {object} context Context object (if a parent component has provided
+	 * 	context)
+	 * @returns {VNode}
 	 */
 	render() {}
 

src/dom/index.js

@@ -2,10 +2,12 @@ import { IS_NON_DIMENSIONAL } from '../constants';
 import options from '../options';
 
 
-/** Create an element with the given nodeName.
- *	@param {String} nodeName
- *	@param {Boolean} [isSvg=false]	If `true`, creates an element within the SVG namespace.
- *	@returns {Element} node
+/**
+ * Create an element with the given nodeName.
+ * @param {string} nodeName
+ * @param {boolean} [isSvg=false]	If `true`, creates an element within the SVG
+ *  namespace.
+ * @returns {Element} node
  */
 export function createNode(nodeName, isSvg) {
 	let node = isSvg ? document.createElementNS('http://www.w3.org/2000/svg', nodeName) : document.createElement(nodeName);
@@ -14,23 +16,27 @@ export function createNode(nodeName, isSvg) {
 }
 
 
-/** Remove a child node from its parent if attached.
- *	@param {Element} node		The node to remove
+/**
+ * Remove a child node from its parent if attached.
+ * @param {Element} node The node to remove
  */
 export function removeNode(node) {
 	let parentNode = node.parentNode;
 	if (parentNode) parentNode.removeChild(node);
 }
 
 
-/** Set a named attribute on the given Node, with special behavior for some names and event handlers.
- *	If `value` is `null`, the attribute/handler will be removed.
- *	@param {Element} node	An element to mutate
- *	@param {string} name	The name/key to set, such as an event or attribute name
- *	@param {any} old	The last value that was set for this name/node pair
- *	@param {any} value	An attribute value, such as a function to be used as an event handler
- *	@param {Boolean} isSvg	Are we currently diffing inside an svg?
- *	@private
+/**
+ * Set a named attribute on the given Node, with special behavior for some names
+ * and event handlers. If `value` is `null`, the attribute/handler will be
+ * removed.
+ * @param {Element} node An element to mutate
+ * @param {string} name The name/key to set, such as an event or attribute name
+ * @param {any} old The last value that was set for this name/node pair
+ * @param {any} value An attribute value, such as a function to be used as an
+ *  event handler
+ * @param {boolean} isSvg Are we currently diffing inside an svg?
+ * @private
  */
 export function setAccessor(node, name, old, value, isSvg) {
 	if (name==='className') name = 'class';
@@ -91,8 +97,9 @@ export function setAccessor(node, name, old, value, isSvg) {
 }
 
 
-/** Attempt to set a DOM property to the given value.
- *	IE & FF throw for certain property-value combinations.
+/**
+ * Attempt to set a DOM property to the given value.
+ * IE & FF throw for certain property-value combinations.
  */
 function setProperty(node, name, value) {
 	try {
@@ -101,8 +108,9 @@ function setProperty(node, name, value) {
 }
 
 
-/** Proxy an event to hooked event handlers
- *	@private
+/**
+ * Proxy an event to hooked event handlers
+ * @private
  */
 function eventProxy(e) {
 	return this._listeners[e.type](options.event && options.event(e) || e);

src/h.js

@@ -11,11 +11,13 @@ const EMPTY_CHILDREN = [];
  * @see http://jasonformat.com/wtf-is-jsx
  * Benchmarks: https://esbench.com/bench/57ee8f8e330ab09900a1a1a0
  *
- * Note: this is exported as both `h()` and `createElement()` for compatibility reasons.
+ * Note: this is exported as both `h()` and `createElement()` for compatibility
+ * reasons.
  *
- * Creates a VNode (virtual DOM element). A tree of VNodes can be used as a lightweight representation
- * of the structure of a DOM tree. This structure can be realized by recursively comparing it against
- * the current _actual_ DOM structure, and applying only the differences.
+ * Creates a VNode (virtual DOM element). A tree of VNodes can be used as a
+ * lightweight representation of the structure of a DOM tree. This structure can
+ * be realized by recursively comparing it against the current _actual_ DOM
+ * structure, and applying only the differences.
  *
  * `h()`/`createElement()` accepts an element name, a list of attributes/props,
  * and optionally children to append to the element.
@@ -30,7 +32,8 @@ const EMPTY_CHILDREN = [];
  *
  * @param {string} nodeName	An element name. Ex: `div`, `a`, `span`, etc.
  * @param {Object} attributes	Any attributes/props to set on the created element.
- * @param rest			Additional arguments are taken to be children to append. Can be infinitely nested Arrays.
+ * @param {...object} rest Additional arguments are taken to be children to
+ *  append. Can be infinitely nested Arrays.
  *
  * @public
  */

src/options.js

@@ -4,15 +4,17 @@
  */
 export default {
 
-	/** If `true`, `prop` changes trigger synchronous component updates.
-	 *	@name syncComponentUpdates
-	 *	@type Boolean
-	 *	@default true
+	/**
+	 * If `true`, `prop` changes trigger synchronous component updates.
+	 * @name syncComponentUpdates
+	 * @type {boolean}
+	 * @default true
 	 */
 	//syncComponentUpdates: true,
 
-	/** Processes all created VNodes.
-	 *	@param {VNode} vnode	A newly-created VNode to normalize/process
+	/**
+	 * Processes all created VNodes.
+	 * @param {VNode} vnode	A newly-created VNode to normalize/process
 	 */
 	//vnode(vnode) { }
 

src/render.js

@@ -1,19 +1,21 @@
 import { diff } from './vdom/diff';
 
-/** Render JSX into a `parent` Element.
- *	@param {VNode} vnode		A (JSX) VNode to render
- *	@param {Element} parent		DOM element to render into
- *	@param {Element} [merge]	Attempt to re-use an existing DOM tree rooted at `merge`
- *	@public
+/**
+ * Render JSX into a `parent` Element.
+ * @param {VNode} vnode A (JSX) VNode to render
+ * @param {Element} parent DOM element to render into
+ * @param {Element} [merge] Attempt to re-use an existing DOM tree rooted at
+ *  `merge`
+ * @public
  *
- *	@example
- *	// render a div into <body>:
- *	render(<div id="hello">hello!</div>, document.body);
+ * @example
+ * // render a div into <body>:
+ * render(<div id="hello">hello!</div>, document.body);
  *
- *	@example
- *	// render a "Thing" component into #foo:
- *	const Thing = ({ name }) => <span>{ name }</span>;
- *	render(<Thing name="one" />, document.querySelector('#foo'));
+ * @example
+ * // render a "Thing" component into #foo:
+ * const Thing = ({ name }) => <span>{ name }</span>;
+ * render(<Thing name="one" />, document.querySelector('#foo'));
  */
 export function render(vnode, parent, merge) {
 	return diff(merge, vnode, {}, false, parent, false);

src/util.js

@@ -1,9 +1,9 @@
 /**
- *  Copy all properties from `props` onto `obj`.
- *  @param {Object} obj		Object onto which properties should be copied.
- *  @param {Object} props	Object from which to copy properties.
- *  @returns obj
- *  @private
+ * Copy all properties from `props` onto `obj`.
+ * @param {Object} obj Object onto which properties should be copied.
+ * @param {Object} props Object from which to copy properties.
+ * @returns {Object}
+ * @private
  */
 export function extend(obj, props) {
 	for (let i in props) obj[i] = props[i];

src/vdom/component-recycler.js

@@ -1,8 +1,10 @@
 import { Component } from '../component';
 
-/** Retains a pool of Components for re-use, keyed on component name.
- *	Note: since component names are not unique or even necessarily available, these are primarily a form of sharding.
- *	@private
+/**
+ * Retains a pool of Components for re-use, keyed on component name.
+ * Note: since component names are not unique or even necessarily available,
+ * these are primarily a form of sharding.
+ * @private
  */
 const components = {};
 
@@ -14,7 +16,10 @@ export function collectComponent(component) {
 }
 
 
-/** Create a component. Normalizes differences between PFC's and classful Components. */
+/**
+ * Create a component. Normalizes differences between PFC's and classful
+ * Components.
+ */
 export function createComponent(Ctor, props, context) {
 	let list = components[Ctor.name],
 		inst;