Specs/howto - Revision history

GPHemsley: GPHemsley moved page Howto spec to Specs/howto: Using subpages for easier navigation.

2013-11-06T14:50:49Z

GPHemsley moved page Howto spec to Specs/howto: Using subpages for easier navigation.

← Older revision	Revision as of 14:50, 6 November 2013
(No difference)

GPHemsley: /* Defining an attribute */ attribute -> object

2013-07-24T12:54:17Z

Defining an attribute: attribute -> object

← Older revision		Revision as of 12:54, 24 July 2013
Line 82:		Line 82:
	* You can omit the "must" statement here for each step (as in the example above) if your conformance section says it is implied. The HTML spec, for example, says in its conformance section that "Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm".		* You can omit the "must" statement here for each step (as in the example above) if your conformance section says it is implied. The HTML spec, for example, says in its conformance section that "Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm".

	* Attributes that return objects should always return the same object. Having an attribute that returns a new ~~attribute~~ each time it is accessed can make seemingly innocuous scripts perform a lot of expensive operations — for example, if such an attribute is used in a loop, every single iteration of the loop would involve allocating and initialising a new object.		* Attributes that return objects should always return the same object. Having an attribute that returns a new object each time it is accessed can make seemingly innocuous scripts perform a lot of expensive operations — for example, if such an attribute is used in a loop, every single iteration of the loop would involve allocating and initialising a new object.

	===Defining a method===		===Defining a method===

Hixie: /* Defining an attribute */

2013-07-23T22:53:01Z

Defining an attribute

← Older revision		Revision as of 22:53, 23 July 2013
Line 81:		Line 81:

	* You can omit the "must" statement here for each step (as in the example above) if your conformance section says it is implied. The HTML spec, for example, says in its conformance section that "Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm".		* You can omit the "must" statement here for each step (as in the example above) if your conformance section says it is implied. The HTML spec, for example, says in its conformance section that "Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm".

			* Attributes that return objects should always return the same object. Having an attribute that returns a new attribute each time it is accessed can make seemingly innocuous scripts perform a lot of expensive operations — for example, if such an attribute is used in a loop, every single iteration of the loop would involve allocating and initialising a new object.

	===Defining a method===		===Defining a method===

Ms2ger: added Category:Specification editing using HotCat

2013-05-09T06:59:54Z

added Category:Specification editing using HotCat

← Older revision		Revision as of 06:59, 9 May 2013
Line 216:		Line 216:

	The old DOM specifications had a particular style of defining methods and attributes that is strongly discouraged (the separation of method definition from arguments, exceptions, and return value). Unfortunately ReSpec.js uses this style by default (consider using [[Anolis]]). E.g. the [http://www.w3.org/TR/DOM-Level-3-Core/core.html#Document3-adoptNode <code>adoptNode()</code> method] in DOM Level 3 Core does not define which exception would be thrown first and more importantently it is not clear at all what the processing model is as you have to piece it together from various independent pieces of information. Therefore please follow the patterns outlined above as demonstrated by the [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#dom-document-adoptnode <code>adoptNode()</code> method] in DOM.		The old DOM specifications had a particular style of defining methods and attributes that is strongly discouraged (the separation of method definition from arguments, exceptions, and return value). Unfortunately ReSpec.js uses this style by default (consider using [[Anolis]]). E.g. the [http://www.w3.org/TR/DOM-Level-3-Core/core.html#Document3-adoptNode <code>adoptNode()</code> method] in DOM Level 3 Core does not define which exception would be thrown first and more importantently it is not clear at all what the processing model is as you have to piece it together from various independent pieces of information. Therefore please follow the patterns outlined above as demonstrated by the [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#dom-document-adoptnode <code>adoptNode()</code> method] in DOM.

			[[Category:Specification editing]]

Hixie: /* Event handler attributes */

2012-07-24T22:19:02Z

Event handler attributes

← Older revision		Revision as of 22:19, 24 July 2012
Line 163:		Line 163:
	====Event handler attributes====		====Event handler attributes====

	HTML defines [http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#events event handlers]. Introducing these on objects upon which events are dispatched is common practice. Excluding markup, the IDL is:		HTML defines [http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#events event handlers]. Introducing these on objects upon which events are dispatched is common practice. Excluding markup, the IDL for adding a "colorchange" event's handler would be:

	~~[TreatNonCallableAsNull]~~ attribute ~~Function? on<var>event</var>~~;		attribute EventHandler oncolorchange;

	In prose you use the following language (replacing ~~<var>Interface</var>~~ with the name of the interface and ~~<var>event</var>~~ with the name of the event):		In prose you use the following language (replacing "Pony" with the name of the interface and "colorchange" with the name of the event):

	<p>The following are the <span data-anolis-spec=html>event handlers</span> (and their corresponding		<p>The following are the <span data-anolis-spec=html>event handlers</span> (and their corresponding
	<span data-anolis-spec=html title="event handler event type">event handler event types</span>) that must		<span data-anolis-spec=html title="event handler event type">event handler event types</span>) that must
	be supported on objects implementing the ~~<var~~>~~Interface<~~/~~var~~> interface:		be supported on objects implementing the <code>Pony</code> interface:

	<table>		<table>
Line 180:		Line 180:
	<tbody>		<tbody>
	<tr>		<tr>
	<td><dfn><code>~~on<var>event</var>~~</code></dfn>		<td><dfn title="event-colorchange"><code>oncolorchange</code></dfn>
	<td><code>~~<var>event</var>~~</code>		<td><code>colorchange</code>
	…		…

Hixie: /* Events implementing their own interface */

2012-07-24T22:15:54Z

Events implementing their own interface

← Older revision		Revision as of 22:15, 24 July 2012
Line 154:		Line 154:
	};</pre>		};</pre>

	<p>The <dfn title=dom-PonyEvent-hairColor><code>hairColor</code></dfn>attribute must		<p>The <dfn title=dom-PonyEvent-hairColor><code>hairColor</code></dfn> attribute must
	return the value it was initialized to. When an		return the value it was initialized to. When an
	<span data-anolis-spec=dom title=concept-event>event</span> is created it must be		<span data-anolis-spec=dom title=concept-event>event</span> is created it must be

Hixie: /* Events implementing their own interface */

2012-07-24T22:15:43Z

Events implementing their own interface

← Older revision		Revision as of 22:15, 24 July 2012
Line 154:		Line 154:
	};</pre>		};</pre>

	<p>The <dfn title=dom-PonyEvent-~~type~~><code>hairColor</code></dfn>attribute must		<p>The <dfn title=dom-PonyEvent-hairColor><code>hairColor</code></dfn>attribute must
	return the value it was initialized to. When an		return the value it was initialized to. When an
	<span data-anolis-spec=dom title=concept-event>event</span> is created it must be		<span data-anolis-spec=dom title=concept-event>event</span> is created it must be

Hixie: /* Events implementing their own interface */

2012-07-24T22:14:38Z

Events implementing their own interface

← Older revision		Revision as of 22:14, 24 July 2012
Line 147:		Line 147:
	<pre class=idl>[Constructor(DOMString <var>type</var>, optional <span>PonyEventInit</span> <var>eventInitDict</var>)]		<pre class=idl>[Constructor(DOMString <var>type</var>, optional <span>PonyEventInit</span> <var>eventInitDict</var>)]
	interface <dfn>PonyEvent</dfn> : <span data-anolis-spec=dom>Event</span> {		interface <dfn>PonyEvent</dfn> : <span data-anolis-spec=dom>Event</span> {
	readonly attribute DOMString <span title=dom-PonyEvent-~~type~~>~~type~~</span>;		readonly attribute DOMString <span title=dom-PonyEvent-hairColor>hairColor</span>;
	};		};

	dictionary <dfn>PonyEventInit</dfn> {		dictionary <dfn>PonyEventInit</dfn> {
	DOMString ~~type~~;		DOMString hairColor;
	};</pre>		};</pre>

	<p>The <dfn title=dom-PonyEvent-type><code>~~type~~</code></dfn>attribute must		<p>The <dfn title=dom-PonyEvent-type><code>hairColor</code></dfn>attribute must
	return the value it was initialized to. When an		return the value it was initialized to. When an
	<span data-anolis-spec=dom title=concept-event>event</span> is created it must be		<span data-anolis-spec=dom title=concept-event>event</span> is created it must be

Annevk: /* Callbacks */

2012-06-06T07:27:19Z

Callbacks

← Older revision		Revision as of 07:27, 6 June 2012
Line 195:		Line 195:

	Note that here we define the object the method was invoked upon as the [http://dev.w3.org/2006/webapi/WebIDL/#dfn-callback-this-value callback this value]. If you want the callback object itself to the this value you do not have to specify it, as that is the default.		Note that here we define the object the method was invoked upon as the [http://dev.w3.org/2006/webapi/WebIDL/#dfn-callback-this-value callback this value]. If you want the callback object itself to the this value you do not have to specify it, as that is the default.

			When dealing with the event loop (task queuing) the task source also needs to be clear. See <canvas>'s [http://www.whatwg.org/C#dom-canvas-toblob toBlob()] method for an example.

	== References ==		== References ==

Annevk: merge Language into Content

2012-05-31T09:44:02Z

merge Language into Content

← Older revision		Revision as of 09:44, 31 May 2012
Line 24:		Line 24:
	== Content ==		== Content ==

	Content in a specification falls into two general categories: ''normative'' and ''informative''. ''Normative'' content includes the requirements and definitions and uses verbs such as ''must'', ''should'', and ''may''. If a normative statement uses the verb ''must'' (and applies to UAs), the browser implementor should be able to write a test case for it. (If it is not possible to write a test case for the statement, do not use the word ''must''.) ''Informative'' content is everything that is not normative. Informative (non-normative) content includes diagrams and code examples—very useful content, but supportive in nature to the actual browser requirements.		Content in a specification falls into two general categories: ''normative'' and ''informative''. ''Normative'' content includes the requirements and definitions and uses verbs such as ''must'', ''should'', and ''may''. Refer to [http://tools.ietf.org/html/rfc2119 RFC 2119] for their definitions. If a normative statement uses the verb ''must'' (and applies to UAs), the browser implementor should be able to write a test case for it. (If it is not possible to write a test case for the statement, do not use the word ''must''.) The verb "may" merely grants permission and is used rarely. Do not use "may not". Normal lowercase is preferred for readability.

			''Informative'' content is everything that is not normative. Informative (non-normative) content includes diagrams and code examples—very useful content, but supportive in nature to the actual browser requirements. Informative content must not include RFC 2119 keywords (use words like "can" or "is" instead).

	See also Hixie's blog post on the subject: http://ln.hixie.ch/?start=1140242962&count=1		See also Hixie's blog post on the subject: http://ln.hixie.ch/?start=1140242962&count=1
Line 193:		Line 195:

	Note that here we define the object the method was invoked upon as the [http://dev.w3.org/2006/webapi/WebIDL/#dfn-callback-this-value callback this value]. If you want the callback object itself to the this value you do not have to specify it, as that is the default.		Note that here we define the object the method was invoked upon as the [http://dev.w3.org/2006/webapi/WebIDL/#dfn-callback-this-value callback this value]. If you want the callback object itself to the this value you do not have to specify it, as that is the default.

	~~== Language ==~~

	Refer to the [http://www.ietf.org/rfc/rfc2119.txt RFC2119] for the definitive use of verbs such as "must", "should", and "may". If you use the verb "must", the implementor must be able to write a test case for this requirement. The verb "may" merely grants permission and is used rarely. Do not use "may not." Do not use RFC2119 keywords in non-normative text such as notes, examples, or statements of facts (use words like "can" or "is" instead). Normal lowercase is preferred for readability.

	== References ==		== References ==