From 10189bbb78db7b143a6d9d62797fc9698363fe4d Mon Sep 17 00:00:00 2001 From: Nathan Youngman Date: Wed, 13 Mar 2024 16:03:34 -0600 Subject: [PATCH] rephrase a few sentences (#3766) Minor tweaks while reading through the docs to hopefully improve readability. --- docs/design/README.md | 10 +++++----- docs/project/principles/information_accumulation.md | 5 ++--- docs/project/principles/safety_strategy.md | 6 +++--- docs/project/roadmap.md | 10 +++++----- 4 files changed, 15 insertions(+), 16 deletions(-) diff --git a/docs/design/README.md b/docs/design/README.md index 850cf12b440a..3eceecbc539e 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -1304,9 +1304,9 @@ fn Positive(a: i64) -> auto { A _block_ is a sequence of _statements_. A block defines a [scope](#declarations-definitions-and-scopes) and, like other scopes, is enclosed in curly braces (`{`...`}`). Each statement is terminated by a -semicolon or block. [Expressions](#expressions), [assignments](assignment.md) -and [`var`](#variable-var-declarations) and [`let`](#constant-let-declarations) -are valid statements. +semicolon or block. [Expressions](#expressions), [assignments](assignment.md), +[`var`](#variable-var-declarations) and [`let`](#constant-let-declarations) are +valid statements. Statements within a block are normally executed in the order they appear in the source code, except when modified by control-flow statements. @@ -3731,8 +3731,8 @@ In conclusion, there are two patterns in how Carbon diverges from C++: - Simplify and removing things to create space for new safety features. This trivially requires breaking backwards compatibility. -- Re-engineer foundations to model and enforce safety. This has complex and - difficulty in C++ without first simplifying the language. +- Re-engineer foundations to model and enforce safety. This is complex and + difficult in C++ without first simplifying the language. This leads to Carbon's incremental path to safety: diff --git a/docs/project/principles/information_accumulation.md b/docs/project/principles/information_accumulation.md index 268f052a9954..5cf324ba70c1 100644 --- a/docs/project/principles/information_accumulation.md +++ b/docs/project/principles/information_accumulation.md @@ -77,9 +77,8 @@ especially important to the coherence of generics and templates. attempt to observe a property of an incomplete class that is not known until the class is complete renders the program invalid. - When an `impl` needs to be resolved, only those `impl` declarations that - have that appear earlier are considered. However, if a later `impl` - declaration would change the result of any earlier `impl` lookup, the - program is invalid. + appear earlier are considered. However, if a later `impl` declaration would + change the result of any earlier `impl` lookup, the program is invalid. ## Exceptions diff --git a/docs/project/principles/safety_strategy.md b/docs/project/principles/safety_strategy.md index cd41580ce1c0..b11f6f4f2acf 100644 --- a/docs/project/principles/safety_strategy.md +++ b/docs/project/principles/safety_strategy.md @@ -694,8 +694,8 @@ Advantages: - Probabilistic safety should come at lower performance cost (including CPU, memory, and disk space). - This will sometimes be significant, and as a result of multiple checks, - could be the difference between the hardened build mode being 50% slower - than the performance build mode and being 200% slower. + could result in the hardened build mode being 50% slower than the + performance build mode instead of being 200% slower. Disadvantages: @@ -767,5 +767,5 @@ addition. If build modes are added for non-safety-related reasons, this may lead to moving build modes out of the safety strategy. **Experiment**: This can be considered an experiment. Carbon may eventually add -more than the initial three build modes, although the reticence to add more is +more than the initial three build modes, although the reluctance to add more is likely to remain. diff --git a/docs/project/roadmap.md b/docs/project/roadmap.md index 36f0812fe2cc..1a72a09a0c53 100644 --- a/docs/project/roadmap.md +++ b/docs/project/roadmap.md @@ -52,8 +52,8 @@ This goal is not necessarily about complete support for the entire language design, but rather enough of it to support building the realistic and interesting Carbon code that interoperates with C++. -Some example language features that we think are key to success here but far -from an exhaustive list: +Here are some example language features that we think are key to success, but +this is far from an exhaustive list: - Imports and a working [prelude] (the earliest stages of a standard library) - Operator overloading and dispatch for expressions @@ -125,9 +125,9 @@ subsequent years. As we adjust our schedule and roadmap to reflect the realistic rate of progress, the _earliest_ it seems feasible to have everything we need to evaluate the 0.1 language is 2025. We're starting to be optimistic in 2024 that we'll be able to -hit this in 2025, but ultimately this remains a lower bound. We may discover as -we progress things that further push out the schedule here. That is the nature -of an experimental project like Carbon. +hit this in 2025, but ultimately this remains a lower bound. As we progress, we +may discover things that push the schedule out further. That is the nature of an +experimental project like Carbon. We expect that once we reach this milestone the community will be able to start realistically evaluating Carbon as a C++ successor language. Of course, this