From c7599c54d861fc006d76821cbea9695361cc0f95 Mon Sep 17 00:00:00 2001 From: Teymour Aldridge Date: Tue, 25 Jan 2022 21:14:36 +0000 Subject: [PATCH] =?UTF-8?q?Tidy=20up=20the=C2=A0documentation.=20(#2404)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - fix a number of typos/grammatical errors - also includes some stylistic changes --- website/docs/advanced-topics/how-it-works.mdx | 12 ++--- website/docs/advanced-topics/portals.mdx | 13 ++++-- website/docs/concepts/html/events.mdx | 4 +- .../concepts/wasm-bindgen/introduction.mdx | 44 +++++++++---------- .../getting-started/build-a-sample-app.mdx | 17 ++++--- website/docs/getting-started/examples.mdx | 2 +- website/docs/getting-started/introduction.mdx | 18 ++++---- .../yew-agent/from-0_1_0-to-0_2_0.mdx | 5 ++- .../yew-router/from-0_15_0-to-0_16_0.mdx | 6 ++- .../yew/from-0_18_0-to-0_19_0.mdx | 24 +++++----- website/docs/more/roadmap.mdx | 1 - website/docs/more/testing.mdx | 4 +- .../version-0.19.0/concepts/html/events.mdx | 4 +- .../concepts/wasm-bindgen/introduction.mdx | 2 +- 14 files changed, 88 insertions(+), 68 deletions(-) diff --git a/website/docs/advanced-topics/how-it-works.mdx b/website/docs/advanced-topics/how-it-works.mdx index 16caea78ff7..17c1d906084 100644 --- a/website/docs/advanced-topics/how-it-works.mdx +++ b/website/docs/advanced-topics/how-it-works.mdx @@ -23,16 +23,18 @@ Using the `html!` macro can feel pretty magic, but it has nothing to hide. If yo how it works, try expanding the `html!` macro calls in your program. There's a useful command called `cargo expand` which allows you to see the expansion of Rust macros. `cargo expand` isn't shipped with `cargo` by default so you'll need to install it with `cargo install cargo-expand` if you haven't -already. +already. [Rust-Analyzer](https://rust-analyzer.github.io/) also provides a mechanism for +[obtaining macro output from within an IDE](https://rust-analyzer.github.io/manual.html#expand-macro-recursively). -Note that when viewing expanded macro code, you're likely to encounter unusually verbose code. The -reason is because generated code can sometimes clash with other code in an application. In order -to prevent issues, `proc_macro` "hygiene" is adhered to. Some examples include: +Output from the `html!` macro is often pretty terse! This is a feature: machine-generated code can +sometimes clash with other code in an application. In order to prevent issues, `proc_macro` +"hygiene" is adhered to. Some examples include: 1. Instead of using `yew::` the macro generates `::yew::` to make sure that the Yew package is referenced correctly. This is also why `::alloc::vec::Vec::new()` is called instead of just `Vec::new()`. -2. Due to potential trait method name collisions, `` is used to make sure that we're using items from the right trait. +2. Due to potential trait method name collisions, `` is used to make sure that we're +using members from the correct trait. ## What is a virtual DOM? diff --git a/website/docs/advanced-topics/portals.mdx b/website/docs/advanced-topics/portals.mdx index b7a449ab8b1..8551dfcc17e 100644 --- a/website/docs/advanced-topics/portals.mdx +++ b/website/docs/advanced-topics/portals.mdx @@ -3,7 +3,7 @@ title: "Portals" description: "Rendering into out-of-tree DOM nodes" --- -## How to think about portals? +## What is a portal? Portals provide a first-class way to render children into a DOM node that exists outside the DOM hierarchy of the parent component. `yew::create_portal(child, host)` returns a `Html` value that renders `child` not hierarchically under its parent component, @@ -11,9 +11,16 @@ but as a child of the `host` element. ## Usage -Typical uses of portals can include modal dialogs and hovercards, as well as more technical applications such as controlling the contents of an element's [`shadowRoot`](https://developer.mozilla.org/en-US/docs/Web/API/Element/shadowRoot), appending stylesheets to the surrounding document's `` and collecting referenced elements inside a central `` element of an ``. +Typical uses of portals can include modal dialogs and hovercards, as well as more technical applications +such as controlling the contents of an element's +[`shadowRoot`](https://developer.mozilla.org/en-US/docs/Web/API/Element/shadowRoot), appending +stylesheets to the surrounding document's `` and collecting referenced elements inside a +central `` element of an ``. -Note that `yew::create_portal` is a rather low-level building block, on which other components should be built that provide the interface for your specific use case. As an example, here is a simple modal dialogue that renders its `children` into an element outside `yew`'s control, identified by the `id="modal_host"`. +Note that `yew::create_portal` is a low-level building block. Libraries should use it to implement +higher-level APIs which can then be consumed by applications. For example, here is a +simple modal dialogue that renders its `children` into an element outside `yew`'s control, +identified by the `id="modal_host"`. ```rust use yew::{html, create_portal, function_component, Children, Properties, Html}; diff --git a/website/docs/concepts/html/events.mdx b/website/docs/concepts/html/events.mdx index 35e700d2ab1..1341e53b030 100644 --- a/website/docs/concepts/html/events.mdx +++ b/website/docs/concepts/html/events.mdx @@ -289,8 +289,8 @@ for the behaviour of `JsCast` but with the smaller scope of events and their tar similar to what you would using `JsCast`. ::: -The `TargetCast` trait builds off of `JsCast` and is specialized towards getting typed event targets -from events. +The `TargetCast` trait is built on top of `JsCast` and is specialized towards getting typed event +targets from events. `TargetCast` comes with Yew so no need to add a dependency in order to use the trait methods on events but it works in a very similar way to `JsCast`. diff --git a/website/docs/concepts/wasm-bindgen/introduction.mdx b/website/docs/concepts/wasm-bindgen/introduction.mdx index f4f27f18a57..df89e4e55b0 100644 --- a/website/docs/concepts/wasm-bindgen/introduction.mdx +++ b/website/docs/concepts/wasm-bindgen/introduction.mdx @@ -7,7 +7,7 @@ sidebar_label: wasm-bindgen high-level interactions between Wasm modules and JavaScript; it is built with Rust by [The Rust and WebAssembly Working Group](https://rustwasm.github.io/). -Yew builds off `wasm-bindgen` and specifically uses the following of its crates: +Yew uses `wasm-bindgen` to interact with the browser through a number of crates: - [`js-sys`](https://crates.io/crates/js-sys) - [`wasm-bindgen`](https://crates.io/crates/wasm-bindgen) @@ -15,7 +15,7 @@ Yew builds off `wasm-bindgen` and specifically uses the following of its crates: - [`web-sys`](https://crates.io/crates/web-sys) This section will explore some of these crates in a high level in order to make it easier to understand -and use `wasm-bindgen` APIs with Yew. For a more in-depth guide into `wasm-bindgen` and it's associated +and use `wasm-bindgen` APIs with Yew. For a more in-depth guide to `wasm-bindgen` and its associated crates then check out [The `wasm-bindgen` Guide](https://rustwasm.github.io/docs/wasm-bindgen/). For documentation on the above crates check out [`wasm-bindgen docs.rs`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/index.html). @@ -33,14 +33,13 @@ types / traits you will see pop up again and again. ### `#[wasm_bindgen]` macro -The `#[wasm_bindgen]` macro, in a high level view, is your translator between Rust and JavaScript, it -allows you to describe imported JavaScript types in terms of Rust and vice versa. Using this macro -is more advanced, and you shouldn't need to reach for it unless you are trying to interop with an -external JavaScript library. The `js-sys` and `web-sys` crates are essentially imported types using -this macro for JavaScript types and the browser API respectively. +The `#[wasm_bindgen]` macro provides an interface between Rust and JavaScript, providing a system +for translating between the two. Using this macro is more advanced, and you shouldn't need to reach +for it unless you are trying to use an external JavaScript library. The `js-sys` and `web-sys` +crates expose `wasm-bindgen` definitions for built-in Javascript types and browser APIs. Let's go over a simple example of using the `#[wasm-bindgen]` macro to import some specific flavours -of the [`console.log`](https://developer.mozilla.org/en-US/docs/Web/API/Console/log). +of the [`console.log`](https://developer.mozilla.org/en-US/docs/Web/API/Console/log) function. ```rust ,no_run use wasm_bindgen::prelude::*; @@ -78,14 +77,15 @@ _This example was adapted from [1.2 Using console.log of The `wasm-bindgen` Guid ### Simulating inheritance -Inheritance between JavaScript classes is a big part of the language and is a major part of how the -Document Object Model (DOM). When types are imported using `wasm-bindgen` you can -also add attributes that describe its inheritance. +Inheritance between JavaScript classes is a core feature of the Javascript language, and the DOM +(Document Object Model) is designed around it. When types are imported using `wasm-bindgen` you can +also add attributes that describe their inheritance. -In Rust this inheritance is simulated using the [`Deref`](https://doc.rust-lang.org/std/ops/trait.Deref.html) +In Rust this inheritance is represented using the [`Deref`](https://doc.rust-lang.org/std/ops/trait.Deref.html) and [`AsRef`](https://doc.rust-lang.org/std/convert/trait.AsRef.html) traits. An example of this might help; so say you have three types `A`, `B`, and `C` where `C` extends `B` which in turn extends `A`. + When importing these types the `#[wasm-bindgen]` macro will implement the `Deref` and `AsRef` traits in the following way: @@ -99,8 +99,7 @@ it was `&B` or `&A`. Its important to note that every single type imported using `#[wasm-bindgen]` has the same root type, you can think of it as the `A` in the example above, this type is [`JsValue`](#jsvalue) which has -its own section -below. +its own section below. _[extends section in The `wasm-bindgen` Guide](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/extends.html)_ @@ -109,19 +108,19 @@ _[extends section in The `wasm-bindgen` Guide](https://rustwasm.github.io/docs/w This is a representation of an object owned by JavaScript, this is a root catch-all type for `wasm-bindgen`. Any type that comes from `wasm-bindgen` is a `JsValue` and this is because JavaScript doesn't have a strong type system so any function that accepts a variable `x` doesn't define its type so `x` can be -a valid JavaScript value; hence `JsValue`. So when you are working with imported functions or types that +a valid JavaScript value; hence `JsValue`. If you are working with imported functions or types that accept a `JsValue`, then any imported value is _technically_ valid. -`JsValue` can be accepted by a function but that function may still only expect certain types and this +`JsValue` can be accepted by a function but that function may still only accept certain types and this can lead to panics - so when using raw `wasm-bindgen` APIs check the documentation of the JavaScript -being imported whether an exception will be caused if that value is not a certain type. +being imported as to whether an exception (panic) will be raised if that value is not a certain type. _[`JsValue` documentation](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/struct.JsValue.html)._ ### [`JsCast`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/trait.JsCast.html) -Rust has a strong type system and JavaScript...doesn't 😞 So in order for Rust to maintain these -strong types but still be convenient the web assembly group came up with a pretty neat trait `JsCast`. +Rust has a strong type system and JavaScript...doesn't 😞. In order for Rust to maintain these +strong types but still be convenient the WebAssembly group came up with a pretty neat trait `JsCast`. Its job is to help you move from one JavaScript "type" to another, which sounds vague, but it means that if you have one type which you know is really another then you can use the functions of `JsCast` to jump from one type to the other. It's a nice trait to get to know when working with `web-sys`, @@ -195,9 +194,10 @@ _[`js-sys` documentation](https://rustwasm.github.io/wasm-bindgen/api/js_sys/ind ## [`wasm-bindgen-futures`](https://crates.io/crates/wasm-bindgen-futures) The `wasm-bindgen-futures` crate provides a bridge for working with JavaScript Promise types as a -Rust Future, and similarly contains utilities to turn a rust Future into a JavaScript Promise. -This can be useful when working with asynchronous or otherwise blocking work in Rust (wasm), -and provides the ability to interoperate with JavaScript events and JavaScript I/O primitives. +Rust [`Future`](https://doc.rust-lang.org/stable/std/future/trait.Future.html), and contains +utilities to turn a rust Future into a JavaScript Promise. This can be useful when working with +asynchronous or otherwise blocking work in Rust (wasm), and provides the ability to interoperate +with JavaScript events and JavaScript I/O primitives. There are three main interfaces in this crate currently: diff --git a/website/docs/getting-started/build-a-sample-app.mdx b/website/docs/getting-started/build-a-sample-app.mdx index 6428567cd9e..74a81f54bdf 100644 --- a/website/docs/getting-started/build-a-sample-app.mdx +++ b/website/docs/getting-started/build-a-sample-app.mdx @@ -31,13 +31,15 @@ cd yew-app ### Run a hello world example -To verify the Rust environment is setup, run the initial project using the cargo build tool. After output about the build process, you should see the expected "Hello World" message. +To verify the Rust environment is setup, run the initial project using `cargo run`. You should see +a "Hello World!" message. ```bash cargo run +# output: Hello World! ``` -### Converting the project into a Yew web application +### Setting up the project as a Yew web application To convert this simple command line application to a basic Yew web application, a few changes are needed. @@ -58,12 +60,13 @@ yew = "0.19" #### Update main.rs -We need to generate a template which sets up a root Component called `App` which renders a button that updates its value when clicked. -Replace the contents of `src/main.rs` with the following code. +We need to generate a template which sets up a root Component called `App` which renders a button +that updates its value when clicked. Replace the contents of `src/main.rs` with the following code. :::note -The line `yew::start_app::()` inside `main()` starts your application and mounts it to the page's `` tag. -If you would like to start your application with any dynamic properties, you can instead use `yew::start_app_with_props::(..)`. +The call to `yew::start_app::()` inside the `main` function starts your application and mounts +it to the page's `` tag. If you would like to start your application with any dynamic +properties, you can instead use `yew::start_app_with_props::(..)`. ::: ```rust ,no_run, title=main.rs @@ -115,7 +118,7 @@ Run the following command to build and serve the application locally. trunk serve ``` -Trunk will helpfully rebuild your application if you modify any of its files. +Trunk will rebuild your application if you modify any of its source code files. ## Congratulations diff --git a/website/docs/getting-started/examples.mdx b/website/docs/getting-started/examples.mdx index c798c34d2e3..b7f396f3f1a 100644 --- a/website/docs/getting-started/examples.mdx +++ b/website/docs/getting-started/examples.mdx @@ -2,7 +2,7 @@ title: "Examples" --- -The Yew repository is chock-full of [examples] (in various states of maintenance). +The Yew repository is contains many [examples] (in various states of maintenance). We recommend perusing them to get a feel for how to use different features of the framework. We also welcome Pull Requests and issues for when they inevitably get neglected and need some ♥️ diff --git a/website/docs/getting-started/introduction.mdx b/website/docs/getting-started/introduction.mdx index 6a494fae208..a84ec5cf1eb 100644 --- a/website/docs/getting-started/introduction.mdx +++ b/website/docs/getting-started/introduction.mdx @@ -5,7 +5,7 @@ description: "Set yourself up for success" --- -Your local development environment will need a couple of tools to compile, build, package and debug your Yew application. +You will need a couple of tools to compile, build, package and debug your Yew application. When getting started, we recommend using [Trunk](https://trunkrs.dev/). Trunk is a WASM web application bundler for Rust. @@ -14,16 +14,17 @@ bundler for Rust. To install Rust, follow the [official instructions](https://www.rust-lang.org/tools/install). :::important -The minimum supported Rust version (MSRV) for Yew is `1.49.0`. Older versions can cause unexpected issues accompanied -by incomprehensible error messages. You can check your toolchain version using `rustup show` (under "active toolchain") -or alternatively `rustc --version`. To update your toolchain, run `rustup update`. +The minimum supported Rust version (MSRV) for Yew is `1.56.0`. Older versions can cause unexpected +issues accompanied by incomprehensible error messages. You can check your toolchain version using +`rustup show` (under "active toolchain") or alternatively `rustc --version`. To update your +toolchain, run `rustup update`. ::: ## Install WebAssembly target -Rust can compile source codes for different "targets" (e.g. different processors). The compilation target for -browser-based WebAssembly is called `wasm32-unknown-unknown`. -The following command will add this target to your development environment. +Rust can compile source codes for different "targets" (e.g. different processors). The compilation +target for browser-based WebAssembly is called `wasm32-unknown-unknown`. The following command will +add the WebAssembly target to your development environment. ```shell rustup target add wasm32-unknown-unknown @@ -31,7 +32,8 @@ rustup target add wasm32-unknown-unknown ## Install Trunk -Trunk is the recommended tool for managing deployment and packaging, and will be used throughout the documentation and examples. +Trunk is the recommended tool for managing deployment and packaging, and is used throughout the +documentation and examples. ```shell # note that this might take a while to install, because it compiles everything from scratch diff --git a/website/docs/migration-guides/yew-agent/from-0_1_0-to-0_2_0.mdx b/website/docs/migration-guides/yew-agent/from-0_1_0-to-0_2_0.mdx index ba736b6ad8a..94e3d07d222 100644 --- a/website/docs/migration-guides/yew-agent/from-0_1_0-to-0_2_0.mdx +++ b/website/docs/migration-guides/yew-agent/from-0_1_0-to-0_2_0.mdx @@ -6,11 +6,12 @@ title: "From 0.1.0 to 0.2.0" The `Context` and `Job` Agents have been removed in favour of Yew's Context API. -You can see the updated [`pub_sub`](https://github.com/yewstack/yew/tree/master/examples/pub_sub) example about how to use Context API. +You can see the updated [`pub_sub`](https://github.com/yewstack/yew/tree/master/examples/pub_sub) +which demonstrate how to use the context API. For users of `yew_agent::utils::store`, you may switch to third party solutions like: [Yewdux](https://github.com/intendednull/yewdux) or [Bounce](https://github.com/futursolo/bounce). -## `Threaded` is separated into `PublicAgent` and `PrivateAgent` +## `Threaded` has been separated into `PublicAgent` and `PrivateAgent` Replace `use yew_agent::Threaded;` with `use yew_agent::PublicAgent;`. diff --git a/website/docs/migration-guides/yew-router/from-0_15_0-to-0_16_0.mdx b/website/docs/migration-guides/yew-router/from-0_15_0-to-0_16_0.mdx index aa454e1dc01..63672ca1290 100644 --- a/website/docs/migration-guides/yew-router/from-0_15_0-to-0_16_0.mdx +++ b/website/docs/migration-guides/yew-router/from-0_15_0-to-0_16_0.mdx @@ -2,6 +2,8 @@ title: "From 0.15.0 to 0.16.0" --- -The router API has been completely redone in `0.16.0`. +The router API has been completely rewritten in `0.16.0`. -There would be to many things to list out here, so we highly recommend to read up on the [router documentation](./../../concepts/router) and adapt your app accordingly. +Because it is such a radical change, there are too many things to list out here, so we highly +recommend to read the updated [router documentation](./../../concepts/router) and adapt your app +accordingly. diff --git a/website/docs/migration-guides/yew/from-0_18_0-to-0_19_0.mdx b/website/docs/migration-guides/yew/from-0_18_0-to-0_19_0.mdx index 59ac6a0f718..579c4d03958 100644 --- a/website/docs/migration-guides/yew/from-0_18_0-to-0_19_0.mdx +++ b/website/docs/migration-guides/yew/from-0_18_0-to-0_19_0.mdx @@ -7,11 +7,12 @@ import TabItem from '@theme/TabItem'; `Yew 0.19.0` has changed a lot, thus this migration will not cover ALL of the changes. -Instead only the most impacting changes are mentioned and the rest should be picked up by cargo. +Instead only the most impactful changes are mentioned and the rest should be picked up by `cargo`. -## html! requirement for braces around most props +## `html!` requirement for braces around most props -Put it simply almost all the time you have to provide braces for props: +The syntax of the `html!` macro has been updated, such that in most cases you will need to enclose +props with braces. @@ -40,7 +41,7 @@ html!{ -Also now you can use a shorthand if prop and variable names are the same: +Shorthand initialization has been added: ```rust {4}, ignore let age = 1; @@ -54,9 +55,10 @@ html!{ -There is a community provided regex to help with this change, though we cant promise it will work all the time. +There is a community provided regex to help automate the update, though we can't promise it will work +all the time. -It for sure breaks when it encounters closures, specifically `|_|` syntax. +It breaks when it encounters closures (specifically the `|_|` syntax). find with `=(?![{">=\s])([^\s>