Tidy up the documentation. (#2404)

- fix a number of typos/grammatical errors - also includes some stylistic changes
yewstack · Jan 25, 2022 · c7599c5 · c7599c5 · github-actions · Jan 25, 2022
1 parent 4580d94
commit c7599c5
Show file tree

Hide file tree

Showing 14 changed files with 88 additions and 68 deletions.
diff --git 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::<module>` the macro generates `::yew::<module>` 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, `<Type as Trait>` is used to make sure that we're using items from the right trait.
+2. Due to potential trait method name collisions, `<Type as Trait>` 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
@@ -3,17 +3,24 @@ 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,
 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 `<head>` and collecting referenced elements inside a central `<defs>` element of an `<svg>`.
+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 `<head>` and collecting referenced elements inside a
+central `<defs>` element of an `<svg>`.
 
-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
@@ -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
@@ -7,15 +7,15 @@ 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)
 - [`wasm-bindgen-futures`](https://crates.io/crates/wasm-bindgen-futures)
 - [`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
@@ -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::<App>()` inside `main()` starts your application and mounts it to the page's `<body>` tag.
-If you would like to start your application with any dynamic properties, you can instead use `yew::start_app_with_props::<App>(..)`.
+The call to `yew::start_app::<App>()` inside the `main` function starts your application and mounts
+it to the page's `<body>` tag. If you would like to start your application with any dynamic
+properties, you can instead use `yew::start_app_with_props::<App>(..)`.
 :::
 
 ```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
@@ -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
@@ -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,24 +14,26 @@ 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
 ```
 
 ## 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
@@ -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
@@ -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
@@ -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.
 
 <Tabs>
   <TabItem value="Invalid" label="Invalid">
@@ -40,7 +41,7 @@ html!{
   </TabItem>
   <TabItem value="Shorthand" label="Shorthand">
 
-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,19 +55,21 @@ html!{
   </TabItem>
 </Tabs>
 
-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></]*(\s!{0,1}[=|&]{2}\s[^\s></]*)*)`
 
 replace with `={$1}`
 
 ## Function components
 
-[Function components](./../../concepts/function-components/introduction) are a brand new way to write components that require less boilerplate than their structural counter part.
+[Function components](./../../concepts/function-components/introduction) are a brand new way to write components that
+requires less boilerplate than their structural counterpart.
 
-While this change does not force you to change your codebase, this migration time is a good opportunity to start using them in your codebase.
+While this change does not force you to change your codebase, as you migrate from `0.18` to `0.19`, this migration time might present a good opportunity to start using them in your codebase.
 
 ## Struct components lifecycle methods and ctx
 
@@ -128,8 +131,9 @@ html! {
 
 ## New crate - yew-agent
 
-Yew agents were removed to their separate crate, see [yew agents migration guide](./../yew-agent/from-0_0_0-to-0_1_0)
+Yew agents were removed to a separate crate, see [yew agents migration guide](./../yew-agent/from-0_0_0-to-0_1_0)
 
 ## Ending note
 
-We are sorry if some things are not covered in this guide as it was truly a huge update and we hope that the uncovered issues will be clearly explained by cargo check/build/clippy.
+We are sorry if some things are not covered in this guide as it was truly a huge update and we hope
+that the uncovered issues will be clearly explained in error messages emitted by the Rust compiler.
Benchmark suite	Current: `c7599c5`	Previous: `4580d94`	Ratio
`yew-struct-keyed 01_run1k`	`186.546`	`164.2255`	`1.14`
`yew-struct-keyed 02_replace1k`	`205.136`	`182.166`	`1.13`
`yew-struct-keyed 03_update10th1k_x16`	`495.699`	`328.3755`	`1.51`
`yew-struct-keyed 04_select1k`	`112.4375`	`67.6965`	`1.66`
`yew-struct-keyed 05_swap1k`	`127.294`	`81.108`	`1.57`
`yew-struct-keyed 06_remove-one-1k`	`38.34`	`27.823`	`1.38`
`yew-struct-keyed 07_create10k`	`2143.543`	`1943.279`	`1.10`
`yew-struct-keyed 08_create1k-after1k_x2`	`419.519`	`370.257`	`1.13`
`yew-struct-keyed 09_clear1k_x8`	`218.448`	`190.033`	`1.15`
`yew-struct-keyed 21_ready-memory`	`0.9634513854980468`	`0.9634513854980468`	`1`
`yew-struct-keyed 22_run-memory`	`1.5057601928710938`	`1.5035057067871094`	`1.00`
`yew-struct-keyed 23_update5-memory`	`1.4615478515625`	`1.5043067932128906`	`0.97`
`yew-struct-keyed 24_run5-memory`	`1.510845184326172`	`1.510845184326172`	`1`
`yew-struct-keyed 25_run-clear-memory`	`1.1463279724121094`	`1.1291122436523438`	`1.02`
`yew-struct-keyed 31_startup-ci`	`1788.44875`	`1786.3202499999998`	`1.00`
`yew-struct-keyed 32_startup-bt`	`32.067999999999984`	`27.35999999999999`	`1.17`
`yew-struct-keyed 34_startup-totalbytes`	`365.9482421875`	`365.9482421875`	`1`