Merge pull request #60 from jplatte/typos-wording

Fix typos, improve wording in latest blog post

Author: matklad

blog/_posts/2020-07-20-three-architectures-for-responsive-ide.adoc

@@ -18,24 +18,24 @@ Specifically, we'll look at the backbone infrastructure of an IDE which serves t
 
 == Map Reduce
 
-The first architecture is reminiscent of map-reduce paradigm.
+The first architecture is reminiscent of the map-reduce paradigm.
 The idea is to split analysis into relatively simple indexing phase, and a separate full analysis phase.
 
 The core constraint of indexing is that it runs on a per-file basis.
-The indexer takes a text of a single file, parses it, and spits out some data about the file.
+The indexer takes the text of a single file, parses it, and spits out some data about the file.
 The indexer can't touch other files.
 
 Full analysis can read other files, and it leverages information from the index to save work.
 
 This all sounds way too abstract, so let's look at a specific example -- Java.
 In Java, each file starts with a package declaration.
 The indexer concatenates the name of the package with a class name to get a fully-qualified name (FQN).
-It also collects the set of method declared in the class, the list of superclasses and interfaces, etc.
+It also collects the set of methods declared in the class, the list of superclasses and interfaces, etc.
 
 Per-file data is merged into an index which maps FQNs to classes.
 Note that constructing this mapping is an embarrassingly parallel task -- all files are parsed independently.
 Moreover, this map is cheap to update.
-When a file change arrives, this file's contribution from the index is removed, the text of file is changed and the indexer runs on the new text and adds new contributions.
+When a file change arrives, this file's contribution from the index is removed, the text of the file is changed and the indexer runs on the new text and adds the new contributions.
 The amount of work to do is proportional to the number of changed files, and is independent from the total number of files.
 
 Let's see how FQN index can be used to quickly provide completion.
@@ -72,27 +72,27 @@ public class Main {
 
 The user has just typed `Foo.f().`, and we need to figure out that the type of receiver expression is `Bar`, and suggest `g` as a completion.
 
-First, as the `Main.java` file is modified, we run the indexer on this single file.
-Nothing has changed (the file still contains `Main` class with static `main` method), so we don't need to update FQN index.
+First, as the file `Main.java` is modified, we run the indexer on this single file.
+Nothing has changed (the file still contains the class `Main` with a static `main` method), so we don't need to update the FQN index.
 
-Next, we need to resolve `Foo` name.
-We parse the file, notice an `import` and lookup `mypackage.Foo` in the FQN index.
+Next, we need to resolve the name `Foo`.
+We parse the file, notice an `import` and look up `mypackage.Foo` in the FQN index.
 In the index, we also find that `Foo` has a static method `f`, so we resolve the call as well.
 The index also stores the return type of `f`, but, and this is crucial, it stores it as a string `"Bar"`, and not as a direct reference to the class `Bar`.
 
 The reason for that is `+import java.util.*+` in `Foo.java`.
 `Bar` can refer either to `java.util.Bar` or to `mypackage.Bar`.
-The indexer doesn't know which one, because it can look *only* at the text of the `Foo.java`.
+The indexer doesn't know which one, because it can look *only* at the text of `Foo.java`.
 In other words, while the index does store the return types of methods, it stores them in an unresolved form.
 
-The next step is to resolve `Bar` identifier in the context of `Foo.java` file.
-This uses FQN index, and lands into the `mypackage.Bar` class.
-There the desired `g` method is found.
+The next step is to resolve the identifier `Bar` in the context of `Foo.java`.
+This uses the FQN index, and lands in the class `mypackage.Bar`.
+There the desired method `g` is found.
 
-All together, only three files were touched during completion.
-FQN index allowed to completely ignore all the other files in the project.
+Altogether, only three files were touched during completion.
+The FQN index allowed us to completely ignore all the other files in the project.
 
-One problem with the approach described thus far is that resolving types from the index requires non-trivial amount of work.
+One problem with the approach described thus far is that resolving types from the index requires a non-trivial amount of work.
 This work might be duplicated if, for example, `Foo.f` is called several times.
 The fix is to add a cache.
 Name resolution results are memoized, so that the cost is paid only once.
@@ -103,28 +103,28 @@ To sum up, the first approach works like this:
 . Each file is being indexed, independently and in parallel, producing a "stub" -- a set of visible top-level declarations, with unresolved types.
 . All stubs are merged into a single index data structure.
 . Name resolution and type inference work primarily off the stubs.
-. Name resolution is lazy (we only resolved type from the stub when we need it) and memoized (each type is resolved only once).
+. Name resolution is lazy (we only resolve a type from the stub when we need it) and memoized (each type is resolved only once).
 . The caches are completely invalidated on every change
 . The index is updated incrementally:
-  * if the edit doesn't change file's stub, no change to the index is required.
+  * if the edit doesn't change the file's stub, no change to the index is required.
   * otherwise, old keys are removed and new keys are added
 
-Note an interesting interplay between "dumb" indexes which can be incrementally updated, and "smart" caches, which are re-computed from scratch.
+Note an interesting interplay between "dumb" indexes which can be updated incrementally, and "smart" caches, which are re-computed from scratch.
 
 This approach combines simplicity and stellar performance.
 The bulk of work is the indexing phase, and you can parallelize and even distribute it across several machine.
-The two example of this architecture are https://www.jetbrains.com/idea/[IntelliJ] and https://sorbet.org/[Sorbet].
+Two examples of this architecture are https://www.jetbrains.com/idea/[IntelliJ] and https://sorbet.org/[Sorbet].
 
 The main drawback of this approach is that it works only when it works -- not every language has a well-defined FQN concept.
-I think overall it's a good idea to design name resolution and module system (mostly boring parts of the language) such that they work well with map-reduce paradigm.
+I think overall it's a good idea to design name resolution and module systems (mostly boring parts of a language) such that they work well with the map-reduce paradigm.
 
-* Require `package` declarations or infer them from a file-system layout
+* Require `package` declarations or infer them from the file-system layout
 * Forbid meta-programming facilities which add new top-level declarations, or restrict them in such way that they can be used by the indexer.
   For example, preprocessor-like compiler plugins that access a single file at a time might be fine.
 * Make sure that each source element corresponds to a single semantic element.
   For example, if the language supports conditional compilation, make sure that it works during name resolution (like Kotlin's https://kotlinlang.org/docs/reference/platform-specific-declarations.html[expect/actual]) and not during parsing (like conditional compilation in most other languages).
   Otherwise, you'd have to index the same file with different conditional compilation settings, and that is messy.
-* Make sure that FQN are enough for most of the name resolution.
+* Make sure that FQNs are enough for most of the name resolution.
 
 The last point is worth elaborating. Let's look at the following Rust example:
 
@@ -158,12 +158,12 @@ However, to make sure that `s.f` indeed refers to `f` from `T`, we also need to
 The second approach places even more restrictions on the language.
 It requires:
 
-* "declaration before use" rule,
+* a "declaration before use" rule,
 * headers or equivalent interface files.
 
 Two such languages are {cpp} and OCaml.
 
-The idea of the approach is simple -- just use traditional compiler, by snapshotting its state immediately after imports for each compilation unit.
+The idea of the approach is simple -- just use a traditional compiler and snapshot its state immediately after imports for each compilation unit.
 An example:
 
 [source,c++]
@@ -175,11 +175,11 @@ void main() {
 }
 ----
 
-Here, the compiler fully processes `iostream` (and any further headers it includes), snapshots its state and proceeds with parsing the program itself.
+Here, the compiler fully processes `iostream` (and any further headers included), snapshots its state and proceeds with parsing the program itself.
 When the user types more characters, the compiler restarts from the point just after the include.
 As the size of each compilation unit itself is usually reasonable, the analysis is fast.
 
-If the user types something into the header file than the caches need to be invalidated.
+If the user types something into the header file, then the caches need to be invalidated.
 However, changes to headers are comparatively rare, most of the code lives in `.cpp` files.
 
 In a sense, headers correspond to the stubs of the first approach, with two notable differences:
@@ -191,7 +191,7 @@ In a sense, headers correspond to the stubs of the first approach, with two nota
 The two examples of this approach are https://github.com/ocaml/merlin[Merlin] of OCaml and https://clangd.llvm.org/[clangd].
 
 The huge benefit of this approach is that it allows re-use of an existing batch compiler.
-Two other approaches described in the article typically result in compiler re-writes.
+The two other approaches described in this article typically result in compiler re-writes.
 The drawback is that almost nobody likes headers and forward declarations.
 
 
@@ -231,8 +231,8 @@ bitflags! {
 ----
 
 `bitflags` is macro which comes from another crate and defines a top-level declaration.
-We can't put the results of macro expansion into the index, because it depends on macro definition in another file.
-We can put macro call itself into an index, but that is mostly useless, as the items, declared by the macro, would miss the index.
+We can't put the results of macro expansion into the index, because it depends on a macro definition in another file.
+We can put the macro call itself into an index, but that is mostly useless, as the items, declared by the macro, would miss the index.
 
 Here's another one:
 
@@ -245,14 +245,14 @@ mod bar;
 ----
 
 Modules `foo` and `bar` refer to the same file, `foo.rs`, which effectively means that items from `foo.rs` are duplicated.
-If `foo.rs` contains `struct S;` declaration, than `foo::S` and `bar::S` are different types.
+If `foo.rs` contains the declaration `struct S;`, then `foo::S` and `bar::S` are different types.
 You also can't fit that into an index, because those `mod` declarations are in a different file.
 
 The second approach doesn't work either.
 In {cpp}, the compilation unit is a single file.
 In Rust, the compilation unit is a whole crate, which consists of many files and is typically much bigger.
-And Rust has procedural macros, which means that even surface analysis of code can take unbounded amount of time.
-And there are no header files, so IDE has to process the whole crate.
+And Rust has procedural macros, which means that even surface analysis of code can take an unbounded amount of time.
+And there are no header files, so the IDE has to process the whole crate.
 Additionally, intra-crate name resolution is much more complicated (declaration before use vs. fixed point iteration intertwined with macro expansion).
 
 It seems that purely laziness based models do not work for Rust.
@@ -262,22 +262,22 @@ For this reason, in rust-analyzer we resort to a smart solution.
 We compensate for the deficit of laziness with incrementality.
 Specifically, we use a generic framework for incremental computation -- https://github.com/salsa-rs/salsa[salsa].
 
-The idea behind salsa is rather simple -- all function calls inside the compiler are instrumented to record which other functions were called during execution.
+The idea behind salsa is rather simple -- all function calls inside the compiler are instrumented to record which other functions were called during their execution.
 The recorded traces are used to implement fine-grained incrementality.
 If after modification the results of all of the dependencies are the same, the old result is reused.
 
 
 There's also an additional, crucial, twist -- if a function is re-executed due to a change in dependency, the new result is compared with the old one.
 If despite a different input they are the same, the propagation of invalidation stops.
 
-Using this engine, we were able to implement rather fancy update strategy.
-Unlike map reduce approach, our indices can store resolved types, which are invalidated only when top-level change occurs.
+Using this engine, we were able to implement a rather fancy update strategy.
+Unlike the map reduce approach, our indices can store resolved types, which are invalidated only when a top-level change occurs.
 Even after a top-level change, we are able to re-use results of most macro expansions.
-And typing inside top-level macro also doesn't invalidate caches unless the expansion of the macro introduces a different set of items.
+And typing inside of a top-level macro also doesn't invalidate caches unless the expansion of the macro introduces a different set of items.
 
 The main benefit of this approach is generality and correctness.
 If you have an incremental computation engine at your disposal, it becomes relatively easy to experiment with the way you structure the computation.
-The code looks mostly like a boring imperative compiler, and you are immune from cache invalidation bugs (we had one, due to procedural macro being non-deterministic).
+The code looks mostly like a boring imperative compiler, and you are immune to cache invalidation bugs (we had one, due to procedural macros being non-deterministic).
 
 The main drawback is extra complexity, slower performance (fine-grained tracking of dependencies takes time and memory) and a feeling that this is a somewhat uncharted territory yet :-)
 

thisweek/_posts/2020-07-06-changelog-32.adoc

@@ -12,7 +12,7 @@ This week we'd like to thank one of our individual sponsors, https://github.com/
 @anp maintains https://moxie.rs[moxie] project: a lightweight platform-agnostic declarative UI runtime, because incremental feedback latency and quality are core to building interactive software.
 
 
-**Become a sponsor:** https://opencollective.com/rust-analyzer/[opecollective.com/rust-analyzer]
+**Become a sponsor:** https://opencollective.com/rust-analyzer/[opencollective.com/rust-analyzer]
 
 == New Features
 

thisweek/_posts/2020-07-13-changelog-33.adoc

@@ -12,7 +12,7 @@ Ferrous Systems offers advice, training, open source development, and proprietar
 This week, Ferrous Systems is running https://oxidizeconf.com/[Oxidize Global], an online conference for embedded systems in Rust!
 Thanks to Ferrous Systems for supporting open source projects like rust-analyzer!
 
-**Become a sponsor:** https://opencollective.com/rust-analyzer/[opecollective.com/rust-analyzer]
+**Become a sponsor:** https://opencollective.com/rust-analyzer/[opencollective.com/rust-analyzer]
 
 == New Features
 

thisweek/_posts/2020-07-20-changelog-34.adoc

@@ -7,7 +7,7 @@ Release: release:2020-07-20[]
 
 == Sponsors
 
-**Become a sponsor:** https://opencollective.com/rust-analyzer/[opecollective.com/rust-analyzer]
+**Become a sponsor:** https://opencollective.com/rust-analyzer/[opencollective.com/rust-analyzer]
 
 == New Features