Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(126)

Side by Side Diff: third_party/WebKit/Source/bindings/IDLExtendedAttributes.md

Issue 2656163005: Convert RuntimeEnabledFeatures.in config file to JSON format. (Closed)
Patch Set: Rebase and add MediaCaptureDepth, MojoJS Created 3 years, 10 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
1 # Blink IDL Extended Attributes 1 # Blink IDL Extended Attributes
2 2
3 [TOC] 3 [TOC]
4 4
5 ## Introduction 5 ## Introduction
6 6
7 The main interest in extended attributes are their _semantics_: Blink implements many more extended attributes than the Web IDL standard, to specify various beh avior. 7 The main interest in extended attributes are their _semantics_: Blink implements many more extended attributes than the Web IDL standard, to specify various beh avior.
8 8
9 The authoritative list of allowed extended attributes and values is [bindings/ID LExtendedAttributes.txt](https://code.google.com/p/chromium/codesearch#chromium/ src/third_party/WebKit/Source/bindings/IDLExtendedAttributes.txt). This is compl ete but not necessarily precise (there may be unused extended attributes or valu es), since validation is run on build, but coverage isn't checked. 9 The authoritative list of allowed extended attributes and values is [bindings/ID LExtendedAttributes.txt](https://code.google.com/p/chromium/codesearch#chromium/ src/third_party/WebKit/Source/bindings/IDLExtendedAttributes.txt). This is compl ete but not necessarily precise (there may be unused extended attributes or valu es), since validation is run on build, but coverage isn't checked.
10 10
(...skipping 1005 matching lines...) Expand 10 before | Expand all | Expand 10 after
1016 [NotEnumerable] attribute DOMString str; 1016 [NotEnumerable] attribute DOMString str;
1017 [NotEnumerable] void foo(); 1017 [NotEnumerable] void foo();
1018 ``` 1018 ```
1019 1019
1020 `[NotEnumerable]` indicates that the method or attribute is not enumerable. 1020 `[NotEnumerable]` indicates that the method or attribute is not enumerable.
1021 1021
1022 ### [OriginTrialEnabled] _(i, m, a, c)_ 1022 ### [OriginTrialEnabled] _(i, m, a, c)_
1023 1023
1024 Summary: Like `[RuntimeEnabled]`, it controls at runtime whether bindings are ex posed, but uses a different mechanism for enabling experimental features. 1024 Summary: Like `[RuntimeEnabled]`, it controls at runtime whether bindings are ex posed, but uses a different mechanism for enabling experimental features.
1025 1025
1026 Usage: `[OriginTrialEnabled=FeatureName]`. FeatureName must be included in [Runt imeEnabledFeatures.in](https://code.google.com/p/chromium/codesearch#chromium/sr c/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.in), and is the same value that would be used with `[RuntimeEnabled]`. 1026 Usage: `[OriginTrialEnabled=FeatureName]`. FeatureName must be included in [Runt imeEnabledFeatures.json5](https://code.google.com/p/chromium/codesearch#chromium /src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.json5), and is th e same value that would be used with `[RuntimeEnabled]`.
1027 1027
1028 ```webidl 1028 ```webidl
1029 [ 1029 [
1030 OriginTrialEnabled=MediaSession 1030 OriginTrialEnabled=MediaSession
1031 ] interface MediaSession { ... }; 1031 ] interface MediaSession { ... };
1032 ``` 1032 ```
1033 1033
1034 When there is an active origin trial for the current execution context, the feat ure is enabled at runtime, and the binding would be exposed to the web. `[Origin TrialEnabled]` also includes a check for the associated runtime flag, so feature s can be enabled in that fashion, even without an origin trial. 1034 When there is an active origin trial for the current execution context, the feat ure is enabled at runtime, and the binding would be exposed to the web. `[Origin TrialEnabled]` also includes a check for the associated runtime flag, so feature s can be enabled in that fashion, even without an origin trial.
1035 1035
1036 `[OriginTrialEnabled]` has similar semantics to `[RuntimeEnabled]`, and is inten ded as a drop-in replacement. For example, `[OriginTrialEnabled]` _cannot_ be ap plied to arguments, see `[RuntimeEnabled]` for reasoning. The key implementation difference is that `[OriginTrialEnabled]` wraps the generated code with `if (Or iginTrials::FeatureNameEnabled(...)) { ...code... }`. 1036 `[OriginTrialEnabled]` has similar semantics to `[RuntimeEnabled]`, and is inten ded as a drop-in replacement. For example, `[OriginTrialEnabled]` _cannot_ be ap plied to arguments, see `[RuntimeEnabled]` for reasoning. The key implementation difference is that `[OriginTrialEnabled]` wraps the generated code with `if (Or iginTrials::FeatureNameEnabled(...)) { ...code... }`.
1037 1037
1038 For more information, see [RuntimeEnabledFeatures](https://code.google.com/p/chr omium/codesearch#chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledF eatures.in) and [OriginTrialContext](https://code.google.com/p/chromium/codesear ch#chromium/src/third_party/WebKit/Source/core/origin_trials/OriginTrialContext. h). 1038 For more information, see [RuntimeEnabledFeatures](https://code.google.com/p/chr omium/codesearch#chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledF eatures.json5) and [OriginTrialContext](https://code.google.com/p/chromium/codes earch#chromium/src/third_party/WebKit/Source/core/origin_trials/OriginTrialConte xt.h).
1039 1039
1040 *** note 1040 *** note
1041 **FIXME:** Currently, `[OriginTrialEnabled]` can only be applied to interfaces, attributes, and constants. Methods (including those generated by `iterable`, `se tlike`, `maplike`, `serializer` and `stringifier`) are not supported. See [Bug 6 21641](https://crbug.com/621641). 1041 **FIXME:** Currently, `[OriginTrialEnabled]` can only be applied to interfaces, attributes, and constants. Methods (including those generated by `iterable`, `se tlike`, `maplike`, `serializer` and `stringifier`) are not supported. See [Bug 6 21641](https://crbug.com/621641).
1042 *** 1042 ***
1043 1043
1044 ### [PostMessage] _(m)_ 1044 ### [PostMessage] _(m)_
1045 1045
1046 Summary: Tells the code generator to generate postMessage method used in Workers , Service Workers etc. 1046 Summary: Tells the code generator to generate postMessage method used in Workers , Service Workers etc.
1047 1047
1048 Usage: `[PostMessage]` can be specified on methods 1048 Usage: `[PostMessage]` can be specified on methods
(...skipping 174 matching lines...) Expand 10 before | Expand all | Expand 10 after
1223 The ReflectOnly attribute limits the range of values that the attribute getter c an return from its reflected attribute. If the content attribute has a value tha t is a case-insensitive match for one of the values given in the `ReflectOnly`'s list (using "`|`" as separator), then it will be returned. To allow attribute v alues that use characters that go beyond what IDL identifiers may contain, strin g literals are used. This is a Blink syntactic extension to extended attributes. 1223 The ReflectOnly attribute limits the range of values that the attribute getter c an return from its reflected attribute. If the content attribute has a value tha t is a case-insensitive match for one of the values given in the `ReflectOnly`'s list (using "`|`" as separator), then it will be returned. To allow attribute v alues that use characters that go beyond what IDL identifiers may contain, strin g literals are used. This is a Blink syntactic extension to extended attributes.
1224 1224
1225 If there is no match, the empty string will be returned. As required by the spec ification, no such checking is performed when the reflected IDL attribute is set . 1225 If there is no match, the empty string will be returned. As required by the spec ification, no such checking is performed when the reflected IDL attribute is set .
1226 1226
1227 `[ReflectOnly=<list>]` should be used if the specification for a reflected IDL a ttribute says it is _"limited to only known values"_. 1227 `[ReflectOnly=<list>]` should be used if the specification for a reflected IDL a ttribute says it is _"limited to only known values"_.
1228 1228
1229 ### [RuntimeEnabled] _(i, m, a, c)_ 1229 ### [RuntimeEnabled] _(i, m, a, c)_
1230 1230
1231 Summary: `[RuntimeEnabled]` wraps the generated code with `if (RuntimeEnabledFea tures::FeatureNameEnabled) { ...code... }`. 1231 Summary: `[RuntimeEnabled]` wraps the generated code with `if (RuntimeEnabledFea tures::FeatureNameEnabled) { ...code... }`.
1232 1232
1233 Usage: `[RuntimeEnabled=FeatureName]`. FeatureName must be included in [RuntimeE nabledFeatures.in](https://code.google.com/p/chromium/codesearch#chromium/src/th ird_party/WebKit/Source/platform/RuntimeEnabledFeatures.in). 1233 Usage: `[RuntimeEnabled=FeatureName]`. FeatureName must be included in [RuntimeE nabledFeatures.in](https://code.google.com/p/chromium/codesearch#chromium/src/th ird_party/WebKit/Source/platform/RuntimeEnabledFeatures.json5).
1234 1234
1235 ```webidl 1235 ```webidl
1236 [ 1236 [
1237 RuntimeEnabled=MediaSession 1237 RuntimeEnabled=MediaSession
1238 ] interface MediaSession { ... }; 1238 ] interface MediaSession { ... };
1239 ``` 1239 ```
1240 1240
1241 Only when the feature is enabled at runtime (using a command line flag, for exam ple, or when it is enabled only in certain platforms), the binding would be expo sed to the web. 1241 Only when the feature is enabled at runtime (using a command line flag, for exam ple, or when it is enabled only in certain platforms), the binding would be expo sed to the web.
1242 1242
1243 `[RuntimeEnabled]` _cannot_ be applied to arguments, as this changes signatures and method resolution and is both very confusing to reason about and implement. For example, what does it mean to mark a _required_ argument as `[RuntimeEnabled ]`? You probably want to apply it only to optional arguments, which are equivale nt to overloads. Thus instead apply `[RuntimeEnabled]` to the _method_, generall y splitting a method in two. For example, instead of: 1243 `[RuntimeEnabled]` _cannot_ be applied to arguments, as this changes signatures and method resolution and is both very confusing to reason about and implement. For example, what does it mean to mark a _required_ argument as `[RuntimeEnabled ]`? You probably want to apply it only to optional arguments, which are equivale nt to overloads. Thus instead apply `[RuntimeEnabled]` to the _method_, generall y splitting a method in two. For example, instead of:
1244 1244
1245 ```webidl 1245 ```webidl
1246 foo(long x, `[RuntimeEnabled=FeatureName]` optional long y); // Don't do this! 1246 foo(long x, `[RuntimeEnabled=FeatureName]` optional long y); // Don't do this!
1247 ``` 1247 ```
1248 1248
1249 do: 1249 do:
1250 1250
1251 ```webidl 1251 ```webidl
1252 // Overload can be replaced with optional if `[RuntimeEnabled]` is removed 1252 // Overload can be replaced with optional if `[RuntimeEnabled]` is removed
1253 foo(long x); 1253 foo(long x);
1254 [RuntimeEnabled=FeatureName] foo(long x, long y); 1254 [RuntimeEnabled=FeatureName] foo(long x, long y);
1255 ``` 1255 ```
1256 1256
1257 For more information, see [RuntimeEnabledFeatures](https://code.google.com/p/chr omium/codesearch#chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledF eatures.in). 1257 For more information, see [RuntimeEnabledFeatures](https://code.google.com/p/chr omium/codesearch#chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledF eatures.json5).
1258 1258
1259 ### [SaveSameObject] _(a)_ 1259 ### [SaveSameObject] _(a)_
1260 1260
1261 Summary: Caches the resulting object and always returns the same object. 1261 Summary: Caches the resulting object and always returns the same object.
1262 1262
1263 When specified, caches the resulting object and returns it in later calls so tha t the attribute always returns the same object. Must be accompanied with `[SameO bject]`. 1263 When specified, caches the resulting object and returns it in later calls so tha t the attribute always returns the same object. Must be accompanied with `[SameO bject]`.
1264 1264
1265 ## Rare Blink-specific IDL Extended Attributes 1265 ## Rare Blink-specific IDL Extended Attributes
1266 1266
1267 These extended attributes are rarely used, generally only in one or two places. These are often replacements for `[Custom]` bindings, and may be candidates for deprecation and removal. 1267 These extended attributes are rarely used, generally only in one or two places. These are often replacements for `[Custom]` bindings, and may be candidates for deprecation and removal.
(...skipping 337 matching lines...) Expand 10 before | Expand all | Expand 10 after
1605 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1605 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1606 1606
1607 1. Redistributions of source code must retain the above copyright notice, this l ist of conditions and the following disclaimer. 1607 1. Redistributions of source code must retain the above copyright notice, this l ist of conditions and the following disclaimer.
1608 1608
1609 2. Redistributions in binary form must reproduce the above copyright notice, thi s list of conditions and the following disclaimer in the documentation and/or ot her materials provided with the distribution. 1609 2. Redistributions in binary form must reproduce the above copyright notice, thi s list of conditions and the following disclaimer in the documentation and/or ot her materials provided with the distribution.
1610 1610
1611 THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS “AS IS” AND ANY EXP RESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIE S OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, I NCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMI TED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFI TS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHE THER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSI BILITY OF SUCH DAMAGE. 1611 THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS “AS IS” AND ANY EXP RESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIE S OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, I NCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMI TED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFI TS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHE THER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSI BILITY OF SUCH DAMAGE.
1612 *** 1612 ***
1613 1613
1614 [CrossOriginProperties]: https://html.spec.whatwg.org/multipage/browsers.html#cr ossoriginproperties-(-o-) 1614 [CrossOriginProperties]: https://html.spec.whatwg.org/multipage/browsers.html#cr ossoriginproperties-(-o-)
OLDNEW
« no previous file with comments | « content/public/common/content_switches.cc ('k') | third_party/WebKit/Source/bindings/IDLExtendedAttributes.txt » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698