Editorial: Use internal variables for DOMQuad's points

Author: zcorpan

geometry/Overview.bs

@@ -414,6 +414,18 @@ dictionary DOMQuadInit {
 };
 </pre>
 
+<p>The following algorithms assume that {{DOMQuad}} objects have the internal member variables <dfn
+dfn-for=quadrilateral id=quadrilateral-point-1>point 1</dfn>, <dfn dfn-for=quadrilateral
+id=quadrilateral-point-2>point 2</dfn>, <dfn dfn-for=quadrilateral id=quadrilateral-point-3>point
+3</dfn>, and <dfn dfn-for=quadrilateral id=quadrilateral-point-4>point 4</dfn>, which are
+{{DOMPoint}} objects. {{DOMQuad}} must be able to access and set the value of these variables. The
+author can modify these {{DOMPoint}} objects, which directly affects the quadrilateral.
+
+<p>An interface returning a {{DOMQuad}} object by an attribute or function may be able to modify
+internal member variable values. Such an interface must specify this ability explicitly in prose.
+
+<p>Internal member variables must not be exposed in any way.
+
 <p>The <dfn dfn-type=constructor dfn-for=DOMQuad><code>DOMQuad(<var>p1</var>, <var>p2</var>,
 <var>p3</var>, <var>p4</var>)</code></dfn> constructor, when invoked, must run the following steps:
 
@@ -430,9 +442,9 @@ dictionary DOMQuadInit {
  <li><p>Let <var>point4</var> be a new {{DOMPoint}} object with its attributes set to the values of
  the namesake dictionary members in <var>p4</var>.
 
- <li><p>Return a new {{DOMQuad}} with {{DOMQuad/p1}} set to <var>point1</var>, {{DOMQuad/p2}} set to
- <var>point2</var>, {{DOMQuad/p3}} set to <var>point3</var> and {{DOMQuad/p4}} set to
- <var>point4</var>.
+ <li><p>Return a new {{DOMQuad}} with <a for=quadrilateral>point 1</a> set to <var>point1</var>, <a
+ for=quadrilateral>point 2</a> set to <var>point2</var>, <a for=quadrilateral>point 3</a> set to
+ <var>point3</var> and <a for=quadrilateral>point 4</a> set to <var>point4</var>.
 </ol>
 
 <p class=note>It is possible to pass {{DOMPoint}}/{{DOMPointReadOnly}} arguments as well. The passed
@@ -448,27 +460,29 @@ a <code>DOMRectInit</code> dictionary</dfn> <var>other</var>, follow these steps
 
 <ol>
  <li><p>Let <var>x</var>, <var>y</var>, <var>width</var> and <var>height</var> be the value of
- <var>other</var>'s {{DOMRectReadOnly/x}}, {{DOMRectReadOnly/y}}, {{DOMRectReadOnly/width}} and
- {{DOMRectReadOnly/height}} attributes, respectively.
+ <var>other</var>'s {{DOMRectInit/x}}, {{DOMRectInit/y}}, {{DOMRectInit/width}} and
+ {{DOMRectInit/height}} dictionary members, respectively.
 
- <li><p>Let <var>point1</var> be a new {{DOMPoint}} object with {{DOMPoint/x}} set to <var>x</var>,
- {{DOMPoint/y}} set to <var>y</var>, {{DOMPoint/z}} set to zero and {{DOMPoint/w}} set to one.
+ <li><p>Let <var>point1</var> be a new {{DOMPoint}} object with <a for=point>x coordinate</a> set to
+ <var>x</var>, <a for=point>y coordinate</a> set to <var>y</var>, <a for=point>z coordinate</a> set
+ to zero and <a for=point>w perspective</a> set to one.
 
- <li><p>Let <var>point2</var> be a new {{DOMPoint}} object with {{DOMPoint/x}} set to <var>x</var> +
- <var>width</var>, {{DOMPoint/y}} set to <var>y</var>, {{DOMPoint/z}} set to zero and {{DOMPoint/w}}
- set to one.
+ <li><p>Let <var>point2</var> be a new {{DOMPoint}} object with <a for=point>x coordinate</a> set to
+ <var>x</var> + <var>width</var>, <a for=point>y coordinate</a> set to <var>y</var>, <a for=point>z
+ coordinate</a> set to zero and <a for=point>w perspective</a> set to one.
 
- <li><p>Let <var>point3</var> be a new {{DOMPoint}} object with {{DOMPoint/x}} set to <var>x</var> +
- <var>width</var>, {{DOMPoint/y}} set to <var>y</var> + <var>height</var>, {{DOMPoint/z}} set to
- zero and {{DOMPoint/w}} set to one.
+ <li><p>Let <var>point3</var> be a new {{DOMPoint}} object with <a for=point>x coordinate</a> set to
+ <var>x</var> + <var>width</var>, <a for=point>y coordinate</a> set to <var>y</var> +
+ <var>height</var>, <a for=point>z coordinate</a> set to zero and <a for=point>w perspective</a> set
+ to one.
 
- <li><p>Let <var>point4</var> be a new {{DOMPoint}} object with {{DOMPoint/x}} set to <var>x</var>,
- {{DOMPoint/y}} set to <var>y</var> + <var>height</var>, {{DOMPoint/z}} set to zero and
- {{DOMPoint/w}} set to one.
+ <li><p>Let <var>point4</var> be a new {{DOMPoint}} object with <a for=point>x coordinate</a> set to
+ <var>x</var>, <a for=point>y coordinate</a> set to <var>y</var> + <var>height</var>, <a for=point>z
+ coordinate</a> set to zero and <a for=point>w perspective</a> set to one.
 
- <li><p>Return a new {{DOMQuad}} with {{DOMQuad/p1}} set to <var>point1</var>, {{DOMQuad/p2}} set to
- <var>point2</var>, {{DOMQuad/p3}} set to <var>point3</var> and {{DOMQuad/p4}} set to
- <var>point4</var>.
+ <li><p>Return a new {{DOMQuad}} with <a for=quadrilateral>point 1</a> set to <var>point1</var>, <a
+ for=quadrilateral>point 2</a> set to <var>point2</var>, <a for=quadrilateral>point 3</a> set to
+ <var>point3</var> and <a for=quadrilateral>point 4</a> set to <var>point4</var>.
 </ol>
 
 <p>The <dfn method lt=fromQuad() dfn-for=DOMQuad><code>fromQuad(<var>other</var>)</code></dfn>
@@ -491,27 +505,19 @@ a <code>DOMQuadInit</code> dictionary</dfn> <var>other</var>, follow these steps
  <li><p>Let <var>point4</var> be the result of invoking <a>create a <code>DOMPoint</code> from the
  dictionary</a> {{DOMQuadInit/p4}} dictionary member of <var>other</var>, if it exists.
 
- <li><p>Return a new {{DOMQuad}} with {{DOMQuad/p1}} set to <var>point1</var>, {{DOMQuad/p2}} set to
- <var>point2</var>, {{DOMQuad/p3}} set to <var>point3</var> and {{DOMQuad/p4}} set to
- <var>point4</var>.
+ <li><p>Return a new {{DOMQuad}} with <a for=quadrilateral>point 1</a> set to <var>point1</var>, <a
+ for=quadrilateral>point 2</a> set to <var>point2</var>, <a for=quadrilateral>point 3</a> set to
+ <var>point3</var> and <a for=quadrilateral>point 4</a> set to <var>point4</var>.
 </ol>
 
 <div dfn-type=attribute dfn-for=DOMQuad>
- <p>The <dfn><code>p1</code></dfn> attribute must return a {{DOMPoint}} that represents <a
- attribute>p1</a> of the quadrilateral it was invoked on. The author can modify the returned
- {{DOMPoint}} object, which directly affects the quadrilateral.
+ <p>The <dfn><code>p1</code></dfn> attribute must return <a for=quadrilateral>point 1</a>.
 
- <p>The <dfn><code>p2</code></dfn> attribute must return a {{DOMPoint}} that represents <a
- attribute>p2</a> of the quadrilateral it was invoked on. The author can modify the returned
- {{DOMPoint}} object, which directly affects the quadrilateral.
+ <p>The <dfn><code>p2</code></dfn> attribute must return <a for=quadrilateral>point 2</a>.
 
- <p>The <dfn><code>p3</code></dfn> attribute must return a {{DOMPoint}} that represents <a
- attribute>p3</a> of the quadrilateral it was invoked on. The author can modify the returned
- {{DOMPoint}} object, which directly affects the quadrilateral.
+ <p>The <dfn><code>p3</code></dfn> attribute must return <a for=quadrilateral>point 3</a>.
 
- <p>The <dfn><code>p4</code></dfn> attribute must return a {{DOMPoint}} that represents <a
- attribute>p4</a> of the quadrilateral it was invoked on. The author can modify the returned
- {{DOMPoint}} object, which directly affects the quadrilateral.
+ <p>The <dfn><code>p4</code></dfn> attribute must return <a for=quadrilateral>point 4</a>.
 </div>
 
 <p>The <dfn method for=DOMQuad>getBounds()</dfn> method, when invoked, must run the following
@@ -520,22 +526,30 @@ algorithm:
 <ol>
   <li><p>Let <var>bounds</var> be a {{DOMRect}} object.
 
-  <li><p>Let <var>left</var> be the minimum of <a attribute>p1</a>.x, <a attribute>p2</a>.x, <a
-  attribute>p3</a>.x and <a attribute>p4</a>.x.
+  <li><p>Let <var>left</var> be the minimum of <a for=quadrilateral>point 1</a>'s <a for=point>x
+  coordinate</a>, <a for=quadrilateral>point 2</a>'s <a for=point>x coordinate</a>, <a
+  for=quadrilateral>point 3</a>'s <a for=point>x coordinate</a> and <a for=quadrilateral>point
+  4</a>'s <a for=point>x coordinate</a>.
 
-  <li><p>Let <var>top</var> be the minimum of <a attribute>p1</a>.y, <a attribute>p2</a>.y, <a
-  attribute>p3</a>.y and <a attribute>p4</a>.y.
+  <li><p>Let <var>top</var> be the minimum of <a for=quadrilateral>point 1</a>'s <a for=point>y
+  coordinate</a>, <a for=quadrilateral>point 2</a>'s <a for=point>y coordinate</a>, <a
+  for=quadrilateral>point 3</a>'s <a for=point>y coordinate</a> and <a for=quadrilateral>point
+  4</a>'s <a for=point>y coordinate</a>.
 
-  <li><p>Let <var>right</var> be the maximum of <a attribute>p1</a>.x, <a attribute>p2</a>.x, <a
-  attribute>p3</a>.x and <a attribute>p4</a>.x.
+  <li><p>Let <var>right</var> be the maximum of <a for=quadrilateral>point 1</a>'s <a for=point>x
+  coordinate</a>, <a for=quadrilateral>point 2</a>'s <a for=point>x coordinate</a>, <a
+  for=quadrilateral>point 3</a>'s <a for=point>x coordinate</a> and <a for=quadrilateral>point
+  4</a>'s <a for=point>x coordinate</a>.
 
-  <li><p>Let <var>bottom</var> be the maximum of <a attribute>p1</a>.y, <a attribute>p2</a>.y, <a
-  attribute>p3</a>.y and <a attribute>p4</a>.y.
+  <li><p>Let <var>bottom</var> be the maximum of <a for=quadrilateral>point 1</a>'s <a for=point>y
+  coordinate</a>, <a for=quadrilateral>point 2</a>'s <a for=point>y coordinate</a>, <a
+  for=quadrilateral>point 3</a>'s <a for=point>y coordinate</a> and <a for=quadrilateral>point
+  4</a>'s <a for=point>y coordinate</a>.
 
-  <li><p>Let <a for=rectangle>x coordinate</a> of <var>bounds</var> be <var>left</var>, <a
-  for=rectangle>y coordinate</a> of <var>bounds</var> be <var>top</var>, <a for=rectangle>width
-  dimension</a> of <var>bounds</var> be <var>right</var> - <var>left</var> and <a
-  for=rectangle>height dimension</a> of <var>bounds</var> be <var>bottom</var> - <var>top</var>.
+  <li><p>Set <a for=rectangle>x coordinate</a> of <var>bounds</var> to <var>left</var>, <a
+  for=rectangle>y coordinate</a> of <var>bounds</var> to <var>top</var>, <a for=rectangle>width
+  dimension</a> of <var>bounds</var> to <var>right</var> - <var>left</var> and <a
+  for=rectangle>height dimension</a> of <var>bounds</var> to <var>bottom</var> - <var>top</var>.
 
   <li><p>Return <var>bounds</var>.
 </ol>
@@ -578,9 +592,9 @@ algorithm:
    <circle cx="10" cy="180" r="3" fill="rgb(204, 51, 51)"/>
   </svg>
   <p class="capture">An irregular quadrilateral represented by a {{DOMQuad}}. The four red colored
-  circles represent the {{DOMPoint}} attributes <a attribute>p1</a> to <a attribute>p4</a>. The
-  dashed rectangle represents the bounding rectangle returned by the {{DOMQuad/getBounds()}} method
-  of the {{DOMQuad}}.
+  circles represent the {{DOMPoint}} attributes {{DOMQuad/p1}} to {{DOMQuad/p4}}. The dashed
+  rectangle represents the bounding rectangle returned by the {{DOMQuad/getBounds()}} method of the
+  {{DOMQuad}}.
  </div>
 </div>