Skip to content

Commit ec8dcaa

Browse files
andruudtabatkins
andcommitted
[css-properties-values-api] Avoid the term 'descriptor'. (w3c#910)
Using 'descriptor' is very confusing since we're going to introduce @Property, which has descriptors in the at-rule sense. Especially "syntax descriptor" is confusing when we're adding an at-rule descriptor named 'syntax'. Co-authored-by: Tab Atkins Jr. <jackalmage@gmail.com>
1 parent 75ec921 commit ec8dcaa

File tree

1 file changed

+38
-38
lines changed

1 file changed

+38
-38
lines changed

css-properties-values-api/Overview.bs

Lines changed: 38 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -67,49 +67,49 @@ Registering custom properties {#registering-custom-properties}
6767
==============================================================
6868

6969
<pre class='idl'>
70-
dictionary PropertyDescriptor {
70+
dictionary PropertyDefinition {
7171
required DOMString name;
7272
DOMString syntax = "*";
7373
required boolean inherits;
7474
DOMString initialValue;
7575
};
7676

7777
partial namespace CSS {
78-
void registerProperty(PropertyDescriptor descriptor);
78+
void registerProperty(PropertyDefinition definition);
7979
};
8080
</pre>
8181

8282
Additional, the {{Document}} object gains a new <dfn attribute for=Window>\[[registeredPropertySet]]</dfn> private slot,
8383
which is a set of records that describe registered custom properties.
8484

85-
The {{PropertyDescriptor}} dictionary {#the-propertydescriptor-dictionary}
85+
The {{PropertyDefinition}} dictionary {#the-propertydefinition-dictionary}
8686
--------------------------------------------------------------------------
8787

88-
A <dfn dictionary>PropertyDescriptor</dfn> dictionary represents author-specified configuration
89-
options for a custom property. {{PropertyDescriptor}} dictionaries contain the
88+
A <dfn dictionary>PropertyDefinition</dfn> dictionary represents author-specified configuration
89+
options for a custom property. {{PropertyDefinition}} dictionaries contain the
9090
following members:
9191

92-
: <dfn dict-member for=PropertyDescriptor>name</dfn>
92+
: <dfn dict-member for=PropertyDefinition>name</dfn>
9393
:: The name of the custom property being defined.
9494

95-
: <dfn dict-member for=PropertyDescriptor>syntax</dfn>
95+
: <dfn dict-member for=PropertyDefinition>syntax</dfn>
9696
:: A string representing how this custom property is parsed.
9797

98-
: <dfn dict-member for=PropertyDescriptor>inherits</dfn>
98+
: <dfn dict-member for=PropertyDefinition>inherits</dfn>
9999
:: True if this custom property should inherit down the DOM tree; False otherwise.
100100

101-
: <dfn dict-member for=PropertyDescriptor>initialValue</dfn>
101+
: <dfn dict-member for=PropertyDefinition>initialValue</dfn>
102102
:: The initial value of this custom property.
103103

104104
The {{registerProperty()}} function {#the-registerproperty-function}
105105
--------------------------------------------------------------------
106106

107-
The <dfn method for=CSS>registerProperty(PropertyDescriptor descriptor)</dfn> method
107+
The <dfn method for=CSS>registerProperty(PropertyDefinition definition)</dfn> method
108108
registers a custom property according to the configuration options provided in
109-
<code>descriptor</code>.
109+
<code>definition</code>.
110110
When it is called,
111111
it executes the <a>register a custom property</a> algorithm,
112-
passing the options in its <code>descriptor</code> argument
112+
passing the options in its <code>definition</code> argument
113113
as arguments of the same names.
114114

115115
<div algorithm>
@@ -142,19 +142,19 @@ as arguments of the same names.
142142
<a>throw</a> an {{InvalidModificationError}}
143143
and exit this algorithm.
144144

145-
3. Attempt to [=consume a syntax descriptor=] from |syntax|.
145+
3. Attempt to [=consume a syntax definition=] from |syntax|.
146146
If it returns failure, <a>throw</a> a {{SyntaxError}}.
147-
Otherwise, let |syntax descriptor| be the returned <a>syntax descriptor</a>.
147+
Otherwise, let |syntax definition| be the returned <a>syntax definition</a>.
148148

149-
4. If |syntax descriptor| is the <a>universal syntax descriptor</a>,
149+
4. If |syntax definition| is the <a>universal syntax definition</a>,
150150
and |initialValue| is not present,
151151
let |parsed initial value| be empty.
152152
This must be treated identically to the "default" initial value of custom properties,
153153
as defined in [[!css-variables]].
154154
Skip to the next step of this algorithm.
155155

156156
Otherwise,
157-
if |syntax descriptor| is the <a>universal syntax descriptor</a>,
157+
if |syntax definition| is the <a>universal syntax definition</a>,
158158
[=CSS/parse=] |initialValue| as a <<declaration-value>>.
159159
If this fails,
160160
<a>throw</a> a {{SyntaxError}}
@@ -168,8 +168,8 @@ as arguments of the same names.
168168
and exit this algorithm.
169169

170170
Otherwise,
171-
[=CSS/parse=] {{PropertyDescriptor/initialValue}}
172-
according to |syntax descriptor|.
171+
[=CSS/parse=] {{PropertyDefinition/initialValue}}
172+
according to |syntax definition|.
173173
If this fails,
174174
<a>throw</a> a {{SyntaxError}}
175175
and exit this algorithm.
@@ -183,7 +183,7 @@ as arguments of the same names.
183183

184184
6. Let |registered property| be a [=struct=]
185185
with a property name of |parsed name|,
186-
a syntax of |syntax descriptor|,
186+
a syntax of |syntax definition|,
187187
an initial value of |parsed initial value|,
188188
and an inherit flag of |inherit flag|.
189189
[=set/Append=] |registered property|
@@ -404,11 +404,11 @@ custom property. Syntax strings consists of
404404
[=syntax component names=], that are
405405
optionally [[#multipliers|multiplied]] and [[#combinator|combined]].
406406

407-
A syntax string can be parsed into a <a>syntax descriptor</a>, which is either:
407+
A syntax string can be parsed into a <a>syntax definition</a>, which is either:
408408

409409
1. A list of <a>syntax components</a>, each of which accept the value types
410410
specified in [[#supported-names]], or
411-
2. The <a>universal syntax descriptor</a> ('*'), which accepts any valid token
411+
2. The <a>universal syntax definition</a> ('*'), which accepts any valid token
412412
stream.
413413

414414
Note: Regardless of the syntax specified, all custom properties accept
@@ -498,7 +498,7 @@ corresponding types accepted by the resulting <a>syntax component</a>.
498498
equivalent to <code>"&lt;transform-function>+"</code>
499499

500500
Note: A syntax string of <code>"*"</code> will produce the
501-
<a>universal syntax descriptor</a>, which is not a <a>syntax component</a>.
501+
<a>universal syntax definition</a>, which is not a <a>syntax component</a>.
502502
Therefore, <code>"*"</code> may not be [[#multipliers|multiplied]] or
503503
[[#combinator|combined]] with anything else.
504504

@@ -529,9 +529,9 @@ The '|' combinator {#combinator}
529529

530530
<a>Syntax strings</a> may use U+007C VERTICAL LINE (|) to provide multiple
531531
<a>syntax component names</a>. Such syntax strings will result in a
532-
<a>syntax descriptor</a> with multiple <a>syntax components</a>.
532+
<a>syntax definition</a> with multiple <a>syntax components</a>.
533533

534-
When a <a>syntax descriptor</a> with multiple <a>syntax components</a> is used
534+
When a <a>syntax definition</a> with multiple <a>syntax components</a> is used
535535
to parse a CSS value, the syntax components are matched in the order specified.
536536

537537
Note: That is, given the syntax string <code>"red | &lt;color>"</code>,
@@ -563,18 +563,18 @@ Parsing the syntax string {#parsing-syntax}
563563
:: A sequence of <a>code points</a> which is either a <a>data type name</a>,
564564
or a sequence that can produce a <<custom-ident>>.
565565

566-
: <dfn>syntax descriptor</dfn>
566+
: <dfn>syntax definition</dfn>
567567
:: An object consisting of a list of <a>syntax components</a>.
568568

569-
: <dfn>universal syntax descriptor</dfn>
570-
:: A special descriptor which accepts any valid token stream.
569+
: <dfn>universal syntax definition</dfn>
570+
:: A special syntax definition which accepts any valid token stream.
571571

572-
### Consume a syntax descriptor ### {#consume-syntax-descriptor}
572+
### Consume a syntax definition ### {#consume-syntax-definition}
573573

574574
<div algorithm>
575-
This section describes how to <dfn export>consume a syntax descriptor</dfn> from a [=string=] |string|.
576-
It either produces a <a>syntax descriptor</a>
577-
with a list of <a>syntax components</a>, or the <a>universal syntax descriptor</a>.
575+
This section describes how to <dfn export>consume a syntax definition</dfn> from a [=string=] |string|.
576+
It either produces a <a>syntax definition</a>
577+
with a list of <a>syntax components</a>, or the <a>universal syntax definition</a>.
578578

579579
1. [=Strip leading and trailing ASCII whitespace=] from |string|.
580580

@@ -583,23 +583,23 @@ Parsing the syntax string {#parsing-syntax}
583583

584584
3. If |string|’s [=string/length=] is 1,
585585
and the only [=code point=] in |string| is U+002A ASTERISK (*),
586-
return the [=universal syntax descriptor=].
586+
return the [=universal syntax definition=].
587587

588588
4. Let |stream| be an [=input stream=] created from the [=code points=] of |string|,
589589
preprocessed as specified in [[css-syntax-3]].
590-
Let |descriptor| be an initially empty [=list=] of <a>syntax components</a>.
590+
Let |definition| be an initially empty [=list=] of <a>syntax components</a>.
591591

592592
5. <a>Consume a syntax component</a> from |stream|.
593593
If failure was returned,
594594
return failure;
595595
otherwise,
596-
[=list/append=] the returned value to |descriptor|.
596+
[=list/append=] the returned value to |definition|.
597597

598598
Consume as much <a>whitespace</a> as possible from |stream|.
599599

600600
Consume the <a>next input code point</a> in |stream|:
601601
: EOF
602-
:: return |descriptor|.
602+
:: return |definition|.
603603

604604
: U+007C VERTICAL LINE (|)
605605
:: Repeat step 5.
@@ -765,7 +765,7 @@ Fallbacks in ''var()'' references {#fallbacks-in-var-references}
765765

766766
References to registered custom properties using the ''var()'' function may
767767
provide a fallback. However, the fallback value must match the
768-
<a>syntax descriptor</a> of the custom property being referenced, otherwise the
768+
<a>syntax definition</a> of the custom property being referenced, otherwise the
769769
declaration is <a spec=css-variables>invalid at computed-value time</a>.
770770

771771
Note: This applies regardless of whether or not the fallback is being used.
@@ -822,7 +822,7 @@ CSSOM {#cssom}
822822

823823
<div algorithm>
824824
To <dfn>reify a registered custom property value</dfn> given a property
825-
|property| and [=syntax descriptor=] |syntax|, run these steps:
825+
|property| and [=syntax definition=] |syntax|, run these steps:
826826

827827
For specified values, [=reify a list of component values=] from the value,
828828
and return the result.
@@ -841,7 +841,7 @@ CSSOM {#cssom}
841841
return the result.
842842
5. If the value is an [=identifier=], [=reify an identifier=] from the value
843843
and return the result.
844-
6. If |syntax| is the [=universal syntax descriptor=],
844+
6. If |syntax| is the [=universal syntax definition=],
845845
[=reify a list of component values=] from the value, and return the
846846
result.
847847
7. Otherwise, [=reify as a CSSStyleValue=] with the

0 commit comments

Comments
 (0)