chore: apply suggestions from code review

Co-authored-by: Ben McCann <[email protected]>

Author: paoloricciuti

DEVELOPER_GUIDE.md

@@ -2,17 +2,17 @@
 
 The aim of this document is to give a general description of the codebase to those who would like to contribute. It will use technical language and will go deep into the various parts of the codebase.
 
-In the most general sense this is how `svelte` works.
+In the most general sense, Svelte works as follows:
 
-- A component is parsed into an AST
-- The AST is analyzed, defining the scopes, finding stateful variables and whatnot
+- A component is parsed into an [abstract syntax tree (AST)](https://en.m.wikipedia.org/wiki/Abstract_syntax_tree) compatible with the [ESTree spec](https://github.com/estree/estree)
+- The AST is analyzed - defining the scopes, finding stateful variables, etc.
 - The AST is transformed, either into a server component or a client component based on the `generate` option. The transformation produces a JS module and some CSS if there's any
 - A server component imports the server runtime from `svelte/internal/server` and when executed with `render` produces a string of the `body` and a string of the `head`
-- A client component imports the client runtime from `svelte/internal/client` and when executed either with `mount` or `hydrate` creates the elements (or retrieves them from the pre-existing DOM in case of hydration), attaches listeners and creates state and effects that are needed to keep the DOM in sync with the state.
+- A client component imports the client runtime from `svelte/internal/client` and when executed - either with `mount` or `hydrate` - creates the DOM elements (or retrieves them from the pre-existing DOM in case of hydration), attaches listeners, and creates state and effects that are needed to keep the DOM in sync with the state.
 
 ## Phase 1: Parsing
 
-Parsing is the first step to convert the component into a runnable JS file. Your `svelte` component is effectively a string and while we could try to do something with regexes and replacements the standard way to do manipulation is to first build an Abstract Syntax Tree and then manipulate that. An Abstract Syntax Tree (AST from now on) is a structured representation of code. Each language has its own syntax and relative AST (based on the parser used). Every JavaScript part of a `svelte` component, be it the script tag or an expression tag in your template, is parsed with `acorn` (`acorn-typescript` in case you use `lang="ts"`) to produce an ESTree compatible tree.
+Parsing is the first step to convert the component into a runnable JS file. Your Svelte component is effectively a string and while we could try to do something with regexes and replacements the standard way to do manipulation is to first build an AST and then manipulate that. An AST is a structured representation of code. Each language has its own syntax and relative AST (based on the parser used). Every JavaScript part of a Svelte component, be it the script tag or an expression tag in your template, is parsed with `acorn` (`acorn-typescript` in case you use `lang="ts"`) to produce an ESTree compatible tree.
 
 If you want a more in-depth explanation of how a Parser works, you can refer to [this video](https://www.youtube.com/watch?v=mwvyKGw2CzU) by @tanhauhau where he builds a mini svelte 4 from scratch, but the gist of it is that you can basically have three main operations during the parsing phase: `eat`, `read` and `match` (with some variations).
 
@@ -40,13 +40,13 @@ if (parser.eat('!--')) {
 
 If the parser doesn't enter this `if`, it will check for all the other language constructs using different strategies to read the information that is needed in the AST (an HTML element for example will need the name, the list of arguments, the fragment etc).
 
-If you want to familiarize yourself with the `svelte` AST, you can go [to the playground](https://svelte.dev/playground), write your `svelte` component and open the `AST Output` tab. This will not only show you the AST of the component but also provide you with hover functionality that will highlight each section of the component when you hover over a section of the AST (and vice versa).
+If you want to familiarize yourself with the Svelte AST, you can go [to the playground](https://svelte.dev/playground), write your Svelte component and open the `AST Output` tab. This will not only show you the AST of the component but also provide you with hover functionality that will highlight each section of the component when you hover over a section of the AST (and vice versa).
 
-![svelte playground showing the AST tab and the hover functionality](assets/developer-guide/ast.png)
+![Svelte playground showing the AST tab and the hover functionality](assets/developer-guide/ast.png)
 
 ## Phase 2: Analysis
 
-Once we have a AST we need to perform analysis on it...during this phase we will collect information about which variables are used, where are they used, if they are stores etc etc. This information will be later used during the third phase to properly transform and optimizing your component (for example if you declare a stateful variable but never reassign to it or never use it in a reactive context we will not bother with creating a stateful variable at all).
+Once we have a AST we need to perform analysis on it. During this phase we will collect information about which variables are used, where are they used, if they are stores etc etc. This information will be later used during the third phase to properly transform and optimizing your component (for example if you declare a stateful variable but never reassign to it or never use it in a reactive context we will not bother with creating a stateful variable at all).
 
 The very first thing to do is to create the scopes for every variable. What this operation does is to create a map from a node to a specific set of references, declarations and declarators. This is useful because if you have a situation like this
 
@@ -70,16 +70,16 @@ The very first thing to do is to create the scopes for every variable. What this
 {count}
 ```
 
-depending on where you read `count` it will refer to a different variable that has been shadowed. The `count` in the template and in `increase` refers to the `count` declared in instance script, while the one in the `log` function will refer to it's argument.
+Depending on where you read `count` it will refer to a different variable that has been shadowed. The `count` in the template and in `increase` refers to the `count` declared in instance script, while the one in the `log` function will refer to its argument.
 
 This is done by walking the AST and manually create a `new Scope` class every time we encounter a node that creates one.
 
 <details>
 	<summary>What does walking the AST means?</summary>
 
-	As we've seen the AST is basically a giant Javascript object with a `type` property to indicate the node type and a series of extra properties.
+	As we've seen, the AST is basically a giant Javascript object with a `type` property to indicate the node type and a series of extra properties.
 
-    For example a `$state(1)` node will look like this (excluding positions information)
+    For example, a `$state(1)` node will look like this (excluding position information):
 
     ```js
     {
@@ -96,7 +96,7 @@ This is done by walking the AST and manually create a `new Scope` class every ti
     }
     ```
 
-    walking allows you to invoke a function (that's called a visitor) for each of the nodes in the AST, receiving the node itself as an argument.
+    Walking allows you to invoke a function (that's called a visitor) for each of the nodes in the AST, receiving the node itself as an argument.
 
 </details>
 
@@ -118,15 +118,15 @@ walk(ast, state, {
 });
 ```
 
-what this snippet of code is doing is
+What this snippet of code is doing is:
 
-- Checking if the function declaration has an Identifier (basically if it's a named or anonymous function)
+- checking if the function declaration has an identifier (basically if it's a named or anonymous function)
 - if it has one it's declaring a new variable in the current scope
 - creating a new scope (since in Javascript when you create a function you are creating a new lexical scope) with the current scope as the parent
 - declare every argument of the function in the newly created scope
 - invoking the next method that will continue the AST traversal, with the brand new scope as the current scope
 
-The same is obviously true for svelte specific nodes too: the `SnippetBlock` visitor looks basically identical to the `FunctionDeclaration` one:
+The same is obviously true for Svelte-specific nodes too: the `SnippetBlock` visitor looks basically identical to the `FunctionDeclaration` one:
 
 ```ts
 walk(ast, state, {
@@ -152,7 +152,7 @@ walk(ast, state, {
 });
 ```
 
-After the initial walk to figure out the right scopes we can now walk once again, we use a generic visitor (that runs before any visit to a node) to pass down the appropriate scope to the node (and collect information about the `// svelte-ignore` comments)
+After the initial walk to figure out the right scopes we can now walk once again, we use a generic visitor (that runs before any visit to a node) to pass down the appropriate scope to the node (and collect information about the `// svelte-ignore` comments):
 
 ```ts
 const visitors = {
@@ -175,4 +175,4 @@ const visitors = {
 };
 ```
 
-this means that in every visitor we can access the `scope` property and ask information about every variable by name.
+This means that in every visitor we can access the `scope` property and ask information about every variable by name.