diff options
author | Allan Sandfeld Jensen <allan.jensen@qt.io> | 2022-05-17 17:24:03 +0200 |
---|---|---|
committer | Allan Sandfeld Jensen <allan.jensen@qt.io> | 2022-06-22 07:51:41 +0000 |
commit | 774f54339e5db91f785733232d3950366db65d07 (patch) | |
tree | 068e1b47bd1af94d77094ed12b604a6b83d9c22a /chromium/styleguide | |
parent | f7eaed5286974984ba5f9e3189d8f49d03e99f81 (diff) | |
download | qtwebengine-chromium-774f54339e5db91f785733232d3950366db65d07.tar.gz |
BASELINE: Update Chromium to 102.0.5005.57
Change-Id: I885f714bb40ee724c28f94ca6bd8dbdb39915158
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>
Diffstat (limited to 'chromium/styleguide')
-rw-r--r-- | chromium/styleguide/c++/blink-c++.md | 2 | ||||
-rw-r--r-- | chromium/styleguide/c++/c++-features.md | 169 | ||||
-rw-r--r-- | chromium/styleguide/python/python.md | 2 | ||||
-rw-r--r-- | chromium/styleguide/web/web.md | 88 |
4 files changed, 163 insertions, 98 deletions
diff --git a/chromium/styleguide/c++/blink-c++.md b/chromium/styleguide/c++/blink-c++.md index 41f4a35f320..c1781611d59 100644 --- a/chromium/styleguide/c++/blink-c++.md +++ b/chromium/styleguide/c++/blink-c++.md @@ -130,6 +130,8 @@ class Document { ``` ### Precede boolean values with words like “is” and “did” + +**Good:** ```c++ bool is_valid; bool did_send_data; diff --git a/chromium/styleguide/c++/c++-features.md b/chromium/styleguide/c++/c++-features.md index 8174319de06..22d4eb596e1 100644 --- a/chromium/styleguide/c++/c++-features.md +++ b/chromium/styleguide/c++/c++-features.md @@ -552,7 +552,7 @@ This feature forces omitting type names. Its use should follow See [discussion thread](https://groups.google.com/a/chromium.org/g/cxx/c/ExfSorNLNf4). *** -### Inline variables +### Inline variables <sup>[allowed]</sup> ```c++ struct S { @@ -606,7 +606,7 @@ requirements exceed `__STDCPP_DEFAULT_NEW_ALIGNMENT__`. None *** -### Type trait variable templates <sup>[tbd]</sup> +### Type trait variable templates <sup>[allowed]</sup> ```c++ bool b = std::is_same_v<int, std::int32_t>; @@ -661,6 +661,37 @@ require default-constructibility of the mapped type. [Discussion thread](https://groups.google.com/a/chromium.org/g/cxx/c/Uv2tUfIwUfQ/m/ffMxCk9uAAAJ) *** +### Non-member std::size/std::empty/std::data <sup>[allowed]</sup> + +```c++ +char buffer[260]; +memcpy(std::data(buffer), source_str.data(), std::size(buffer)); + +if (!std::empty(container)) { ... } +``` + +**Description:** Non-member versions of what are often member functions on STL +containers. Primarily useful when: +- using `std::size()` as a replacement for the old `arraysize()` macro. +- writing code that needs to generically operate across things like + `std::vector` and `std::list` (which provide `size()`, `empty()`, and `data() + member functions), `std::array` and `std::initialize_list` (which only provide + a subset of the aforementioned member functions), and regular arrays (which + have no member functions at all). + +**Documentation:** +[std::size](https://en.cppreference.com/w/cpp/iterator/size), +[std::empty](https://en.cppreference.com/w/cpp/iterator/empty), +[std::data](https://en.cppreference.com/w/cpp/iterator/data) + +**Notes:** +*** promo +[Discussion thread](https://groups.google.com/a/chromium.org/g/cxx/c/58qlA3zk5ZI/m/7kKok65xAAAJ) + +Prefer range-based for loops over `std::size()`: range-based for loops work even +for regular arrays. +*** + ## C++17 Banned Library Features {#library-blocklist-17} The following C++17 library features are not allowed in the Chromium codebase. @@ -790,6 +821,67 @@ std::chrono::round<std::chrono::seconds>(time_pt); Banned since `std::chrono` is banned. *** +### std::variant <sup>[banned]</sup> + +```c++ +std::variant<int, double> v = 12; +``` + +**Description:** The class template `std::variant` represents a type-safe +`union`. An instance of `std::variant` at any given time holds a value of one of +its alternative types (it's also possible for it to be valueless). + +**Documentation:** +[std::variant](https://en.cppreference.com/w/cpp/utility/variant) + +**Notes:** +*** promo +Banned for now because it does not provide safety guarantees in the case of +misuse. The Chromium C++ team is investigating the possibility of hardening the +C++ library so that the standard version can be used. In the meanwhile, use +`absl::variant` instead. +*** + +### std::optional <sup>[banned]</sup> + +```c++ +std::optional<std::string> s; +``` + +**Description:** The class template `std::optional` manages an optional +contained value, i.e. a value that may or may not be present. A common use case +for optional is the return value of a function that may fail. + +**Documentation:** +[std::optional](https://en.cppreference.com/w/cpp/utility/optional) + +**Notes:** +*** promo +Banned for now because it does not provide safety guarantees in the case of +misuse. The Chromium C++ team is investigating the possibility of hardening the +C++ library so that the standard version can be used. In the meanwhile, use +`absl::optional` instead. +*** + +### std::clamp <sup>[banned]</sup> + +```c++ +int x = std::clamp(inp, 0, 100); +``` + +**Description:** Clamps a value between a minimum and a maximum. + +**Documentation:** +[std::clamp](https://en.cppreference.com/w/cpp/algorithm/clamp) + +**Notes:** +*** promo +Banned for now because it does not provide safety guarantees in the case of +misuse. The Chromium C++ team is investigating the possibility of hardening the +C++ library so that the standard version can be used. In the meanwhile, use +`base::clamp` instead. +*** + ## C++17 TBD Language Features {#core-review-17} The following C++17 language features are not allowed in the Chromium codebase. @@ -930,42 +1022,6 @@ The following C++17 library features are not allowed in the Chromium codebase. See the top of this page on how to propose moving a feature from this list into the allowed or banned sections. -### std::variant <sup>[tbd]</sup> - -```c++ -std::variant<int, double> v = 12; -``` - -**Description:** The class template `std::variant` represents a type-safe -`union`. An instance of `std::variant` at any given time holds a value of one of -its alternative types (it's also possible for it to be valueless). - -**Documentation:** -[std::variant](https://en.cppreference.com/w/cpp/utility/variant) - -**Notes:** -*** promo -See also `absl::variant`. -*** - -### std::optional <sup>[tbd]</sup> - -```c++ -std::optional<std::string> s; -``` - -**Description:** The class template `std::optional` manages an optional -contained value, i.e. a value that may or may not be present. A common use case -for optional is the return value of a function that may fail. - -**Documentation:** -[std::optional](https://en.cppreference.com/w/cpp/utility/optional) - -**Notes:** -*** promo -See also `absl::optional`. -*** - ### std::string_view <sup>[tbd]</sup> ```c++ @@ -1290,22 +1346,6 @@ objects with the same value have the same object representation. None *** -### std::clamp <sup>[tbd]</sup> - -```c++ -int x = base::clamp(inp, 0, 100); -``` - -**Description:** Clamps a value between a minimum and a maximum. - -**Documentation:** -[std::clamp](https://en.cppreference.com/w/cpp/algorithm/clamp) - -**Notes:** -*** promo -See also `base::clamp`. -*** - ### std::reduce <sup>[tbd]</sup> ```c++ @@ -1390,27 +1430,6 @@ static_assert(std::lcm(12, 18) == 36); None *** -### Non-member std::size/std::empty/std::data <sup>[tbd]</sup> - -```c++ -for (std::size_t i = 0; i < std::size(c); ++i) { ... -if (!std::empty(c)) { ... -std::strcpy(arr, std::data(str)); -``` - -**Description:** Non-member versions of what are normally member functions, for -symmetrical use with things like arrays and initializer_lists. - -**Documentation:** -[std::size](https://en.cppreference.com/w/cpp/iterator/size), -[std::empty](https://en.cppreference.com/w/cpp/iterator/empty), -[std::data](https://en.cppreference.com/w/cpp/iterator/data) - -**Notes:** -*** promo -See `base::size`, `base::empty`, and `base::data`. -*** - ### Mathematical special functions <sup>[tbd]</sup> ```c++ diff --git a/chromium/styleguide/python/python.md b/chromium/styleguide/python/python.md index 54543fe9430..6f8bcd081de 100644 --- a/chromium/styleguide/python/python.md +++ b/chromium/styleguide/python/python.md @@ -5,7 +5,7 @@ guides](https://chromium.googlesource.com/chromium/src/+/main/styleguide/stylegu As of 2021-05-12, Chromium is transitioning from Python 2 to Python 3 (follow [crbug.com/941669](https://crbug.com/941669) for updates). See -[//docs/python3_migration.md](../docs/python3_migration.md) for more on +[//docs/python3_migration.md](../../docs/python3_migration.md) for more on how to migrate code. For new (Python 3) code, you can assume Python 3.8 (and that's what the bots diff --git a/chromium/styleguide/web/web.md b/chromium/styleguide/web/web.md index b648c923cbb..23bfdd87459 100644 --- a/chromium/styleguide/web/web.md +++ b/chromium/styleguide/web/web.md @@ -290,7 +290,10 @@ Use RTL-friendly versions of things like `margin` or `padding` where possible: For properties that don't have an RTL-friendly alternatives, use `html[dir='rtl']` as a prefix in your selectors. -## JavaScript +## JavaScript/TypeScript + +New WebUI code (except for ChromeOS specific code) should be written in +TypeScript. ### Style @@ -308,7 +311,7 @@ Guide](https://google.github.io/styleguide/jsguide.html) as well as * Use `@type` (instead of `@return` or `@param`) for JSDoc annotations on getters/setters -* See [Annotating JavaScript for the Closure +* For legacy code using closure, see [Annotating JavaScript for the Closure Compiler](https://developers.google.com/closure/compiler/docs/js-for-compiler) for @ directives @@ -320,6 +323,9 @@ Guide](https://google.github.io/styleguide/jsguide.html) as well as ### Closure compiler +* Closure compiler should only be used by legacy code that has not yet been + converted to use TypeScript. + * Use the [closure compiler](https://chromium.googlesource.com/chromium/src/+/main/docs/closure_compilation.md) to identify JS type errors and enforce correct JSDoc annotations. @@ -361,20 +367,20 @@ Guide](https://google.github.io/styleguide/jsguide.html) as well as Also see the [Google Polymer Style Guide](http://go/polymer-style). -* Elements with UI should have their HTML in a .html file and logic in a JS file - with the same name. The HTML should be copied into the final JS file at build - time, replacing the special `{__html_template__}` sequence, using the - html_to_js BUILD.gn rule. For example the following will paste the contents - of my_app.html into the final generated JS file: +* Elements with UI should have their HTML in a .html file and logic in a TS file + with the same name. The HTML template can be imported into the final JS file + at runtime from a generated JS wrapper file via the getTemplate() function. + THe wrapper file is generated using the html_to_wrapper gn rule: ``` - html_to_js('web_components') { - js_files = [ 'my_app.js' ] + html_to_wrapper('html_wrapper_files') { + in_files = [ 'my_app.html' ] } ``` * In new code, use class based syntax for custom elements. Example: ```js -import {html, PolymerElement} from 'chrome://resources/polymer/v3_0/polymer/polymer_bundled.min.js'; +import {PolymerElement} from 'chrome://resources/polymer/v3_0/polymer/polymer_bundled.min.js'; +import {getTemplate} from './my_app.html.js'; class MyAppElement extends PolymerElement { static get is() { @@ -382,7 +388,7 @@ class MyAppElement extends PolymerElement { } static get template() { - return html`{__html_template__}`; + return getTemplate(); } static get properties() { @@ -390,6 +396,8 @@ class MyAppElement extends PolymerElement { foo: String, }; } + + foo: string; } customElements.define(MyAppElement.is, MyAppElement); @@ -409,6 +417,17 @@ customElements.define(MyAppElement.is, MyAppElement); * Use camelCase for element IDs to simplify local DOM accessors (i.e. `this.$.camelCase` instead of `this.$['dash-case']`). +* Note: In TypeScript, the `this.$.camelCase` accessor requires adding an + interface: + +```js +interface MyAppElement { + $: { + camelCase: HTMLElement, + }; +} +``` + * Use `this.foo` instead of `newFoo` arguments in observers when possible. This makes changing the type of `this.foo` easier (as the `@type` is duplicated in less places, i.e. `@param`). @@ -473,8 +492,9 @@ be passed to the generate_grd rule to generate entries for them in a grd file. ### Example The following BUILD.gn example code uses preprocess_if_expr to preprocess any -`<if expr>` in the final my_app.js file that is generated by the earlier -html_to_js example. It then uses the manifest from this operation and the +`<if expr>` in my_app.ts and in the my_app.html.ts file that is generated by +the earlier html_to_wrapper example. It then runs the TypeScript compiler on +the outputs of this operation and uses the manifest from this operation and the in_files option to place both the final, preprocessed file and a separate (not preprocessed) icon into a generated grd file using generate_grd: @@ -482,21 +502,45 @@ preprocessed) icon into a generated grd file using generate_grd: preprocess_folder = "preprocessed" preprocess_manifest = "preprocessed_manifest.json" -# Read file from target_gen_dir, where it will be pasted by html_to_js. preprocess_if_expr("preprocess") { - deps = [ ":web_components" ] + in_folder = "." + in_files = [ "my_app.ts" ] + out_folder = "$target_gen_dir/$preprocess_folder" +} + +# Read file from target_gen_dir, where it will be pasted by html_to_wrapper. +preprocess_if_expr("preprocess_generated") { in_folder = target_gen_dir - in_files = [ "my_app.js" ] + in_files = [ "my_app.html.ts" ] out_folder = "$target_gen_dir/$preprocess_folder" - out_manifest = "$target_gen_dir/$preprocess_manifest" + deps = [ ":html_wrapper_files" ] +} + +# Run TS compiler on the two files: +ts_library("build_ts") { + root_dir = "$target_gen_dir/$preprocess_folder" + out_dir = "$target_gen_dir/tsc" + tsconfig_base = "tsconfig_base.json" + in_files = [ + "my_app.html.ts", + "my_app.ts", + ] + deps = [ + "//third_party/polymer/v3_0:library", + "//ui/webui/resources:library", + ] + extra_deps = [ + ":preprocess", + ":preprocess_generated", + ] } -# Put the preprocessed file as well as a separate my_icon.svg file in the grd: +# Put the compiled files as well as a separate my_icon.svg file in the grd: generate_grd("build_grd") { input_files = [ "my_icon.svg" ] input_files_base_dir = rebase_path(".", "//") - deps = [ ":preprocess" ] - manifest_files = [ "$target_gen_dir/$preprocess_manifest" ] + deps = [ ":build_ts" ] + manifest_files = [ "$target_gen_dir/tsconfig.manifest" ] grd_prefix = [ "foo" ] out_grd = "$target_gen_dir/resources.grd" } @@ -510,7 +554,7 @@ In a few legacy resources, preprocessing is enabled by adding the Note #2: These preprocessor statements can live in places that surprise linters or -formatters (for example: running clang-format on a .js file with an `<if>` in +formatters (for example: running clang-format on a .ts file with an `<if>` in it). Generally, putting these language-invalid features inside of comments helps alleviate problems with unexpected input. *** @@ -521,7 +565,7 @@ or excluding code. Example: ```js -function isWindows() { +function isWindows(): boolean { // <if expr="win"> return true; // </if> |