Add clarifications and fluff

--HG--
extra : rebase_source : 0df21ff398fd077dd1bde480fff44919329a3aeb

Author: tabatkins

css-font-load-events/Overview.html

@@ -345,6 +345,12 @@ <h4 class="heading settled heading" data-level=2.2.1 id=font-face-constructor><s
 <h4 class="heading settled heading" data-level=2.2.2 id=font-face-load><span class=secno>2.2.2 </span><span class=content>
 The <code>load()</code> method</span><a class=self-link href=#font-face-load></a></h4>
 
+<p>	The <a class=idl-code data-link-for=FontFace data-link-type=method href=#dom-fontface-load>load()</a> method of <a class=idl-code data-link-type=interface>FontFace</a>
+	forces a url-based font face to request its font data and load.
+	For fonts constructed from binary data,
+	or fonts that are already loading or loaded,
+	it does nothing.
+
 <p>	When the <dfn class=idl-code data-dfn-for=FontFace data-dfn-type=method data-export="" id=dom-fontface-load>load()<a class=self-link href=#dom-fontface-load></a></dfn> method is called,
 	execute these steps:
 
@@ -388,6 +394,11 @@ <h4 class="heading settled heading" data-level=2.2.2 id=font-face-load><span cla
 <h4 class="heading settled heading" data-level=2.2.3 id=font-face-ready><span class=secno>2.2.3 </span><span class=content>
 The <code>ready()</code> method</span><a class=self-link href=#font-face-ready></a></h4>
 
+<p>	The <a class=idl-code data-link-for=FontFace data-link-type=method href=#dom-fontface-ready>ready()</a> method of <a class=idl-code data-link-type=interface>FontFace</a>
+	returns a Promise
+	which is fulfilled when the font face is successfully loaded,
+	or rejected when the font face fails to load or parse successfully.
+
 <p>	When the <dfn class=idl-code data-dfn-for=FontFace data-dfn-type=method data-export="" id=dom-fontface-ready>ready()<a class=self-link href=#dom-fontface-ready></a></dfn> method is called,
 	execute these steps:
 
@@ -402,11 +413,15 @@ <h4 class="heading settled heading" data-level=2.2.3 id=font-face-ready><span cl
 <h4 class="heading settled heading" data-level=2.2.4 id=font-face-match><span class=secno>2.2.4 </span><span class=content>
 The <code>match()</code> method</span><a class=self-link href=#font-face-match></a></h4>
 
+<p>	The <a class=idl-code data-link-for=FontFace data-link-type=method href=#dom-fontface-matchfontfacedescriptors-descriptors-optional-domstring-characters>match()</a> method of <a class=idl-code data-link-type=interface>FontFace</a> exposes the CSS font-matching algorithm
+	on a per-font basis,
+	allowing one to test individual fonts to see if they match a given <a class=property data-link-type=propdesc href=http://dev.w3.org/csswg/css-fonts-3/#propdef-font title=font>font</a> value.
+
 <p>	When the <dfn class=idl-code data-dfn-for=FontFace data-dfn-type=method data-export="" id=dom-fontface-matchfontfacedescriptors-descriptors-optional-domstring-characters title=match()>match(<a class=idl-code data-link-type=interface>FontFaceDescriptors</a> <dfn class=idl-code data-dfn-for="FontFace/match() match()" data-dfn-type=argument data-export="" id=dom-fontfacematch-match-descriptors>descriptors<a class=self-link href=#dom-fontfacematch-match-descriptors></a></dfn>, optional DOMString <dfn class=idl-code data-dfn-for="FontFace/match() match()" data-dfn-type=argument data-export="" id=dom-fontfacematch-match-characters>characters<a class=self-link href=#dom-fontfacematch-match-characters></a></dfn>)<a class=self-link href=#dom-fontface-matchfontfacedescriptors-descriptors-optional-domstring-characters></a></dfn> method is called,
 	execute these steps:
 
-	<p class=issue id=issue-7d93b920><a class=self-link href=#issue-7d93b920></a>
-		Refer to Font’s font matching algorithm somehow.
+	<p class=issue id=issue-89af42f8><a class=self-link href=#issue-89af42f8></a>
+		Figure out how to run Font’s font selection algorithm on a single face.
 
 <h4 class="heading settled heading" data-level=2.2.5 id=font-face-css-connection><span class=secno>2.2.5 </span><span class=content>
 Connection to CSS’s <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule>@font-face</a></span><a class=self-link href=#font-face-css-connection></a></h4>
@@ -796,6 +811,10 @@ <h4 class="heading settled heading" data-level=2.3.5 id=font-face-set-ready><spa
 	The <a>ready promise</a> is only fulfilled after layout operations complete 
 	and no additional font loads are necessary.
 
+<p class=note>	Note: Note that the Promise returned by this <a class=idl-code data-link-for=FontFaceSet data-link-type=method href=#dom-fontfaceset-ready>ready()</a> method is only ever fulfilled,
+	never rejected,
+	unlike the Promise returned by the <a class=idl-code data-link-type=interface>FontFace</a> <a class=idl-code data-link-for=FontFace data-link-type=method href=#dom-fontface-ready>ready()</a> method.
+
 <h3 class="heading settled heading" data-level=2.4 id=font-load-event-examples><span class=secno>2.4 </span><span class=content>
 Font load event examples</span><a class=self-link href=#font-load-event-examples></a></h3>
 
@@ -1093,9 +1112,9 @@ <h2 class="no-num no-ref heading settled heading" id=property-index><span class=
 		I think I just need to add it to WorkerGlobalScope or something.
 
 <a href=#issue-fbb9c14f> ↵ </a><p class=issue>
-		Refer to Font’s font matching algorithm somehow.
+		Figure out how to run Font’s font selection algorithm on a single face.
 
-<a href=#issue-7d93b920> ↵ </a><p class=issue>
+<a href=#issue-89af42f8> ↵ </a><p class=issue>
 		Document the FontFaceSet behavior for Workers.
 		(They start out empty, but can construct fonts or be sent them via postMessage.)
 

css-font-load-events/Overview.src.html

@@ -266,6 +266,12 @@ <h4 id='font-face-constructor'>
 <h4 id='font-face-load'>
 The <code>load()</code> method</h4>
 
+	The <a method for=FontFace>load()</a> method of <a interface>FontFace</a>
+	forces a url-based font face to request its font data and load.
+	For fonts constructed from binary data,
+	or fonts that are already loading or loaded,
+	it does nothing.
+
 	When the <dfn method for=FontFace>load()</dfn> method is called,
 	execute these steps:
 
@@ -309,6 +315,11 @@ <h4 id='font-face-load'>
 <h4 id='font-face-ready'>
 The <code>ready()</code> method</h4>
 
+	The <a method for=FontFace>ready()</a> method of <a interface>FontFace</a>
+	returns a Promise
+	which is fulfilled when the font face is successfully loaded,
+	or rejected when the font face fails to load or parse successfully.
+
 	When the <dfn method for="FontFace">ready()</dfn> method is called,
 	execute these steps:
 
@@ -323,11 +334,15 @@ <h4 id='font-face-ready'>
 <h4 id='font-face-match'>
 The <code>match()</code> method</h4>
 
+	The <a method for=FontFace>match()</a> method of <a interface>FontFace</a> exposes the CSS font-matching algorithm
+	on a per-font basis,
+	allowing one to test individual fonts to see if they match a given 'font' value.
+
 	When the <dfn method for="FontFace" title='match()'>match(<a interface>FontFaceDescriptors</a> <dfn argument>descriptors</dfn>, optional DOMString <dfn argument>characters</dfn>)</dfn> method is called,
 	execute these steps:
 
 	<p class='issue'>
-		Refer to Font's font matching algorithm somehow.
+		Figure out how to run Font's font selection algorithm on a single face.
 
 <h4 id='font-face-css-connection'>
 Connection to CSS's ''@font-face''</h4>
@@ -719,6 +734,10 @@ <h4 id='font-face-set-ready'>
 	The <a>ready promise</a> is only fulfilled after layout operations complete 
 	and no additional font loads are necessary.
 
+	Note: Note that the Promise returned by this <a method for=FontFaceSet>ready()</a> method is only ever fulfilled,
+	never rejected,
+	unlike the Promise returned by the <a interface>FontFace</a> <a method for=FontFace>ready()</a> method.
+
 <h3 id="font-load-event-examples">
 Font load event examples</h3>