Wording

Author: iluuu1994

docs/source/core/data-structures/zval.rst

@@ -5,7 +5,7 @@
 PHP is a dynamic language. As such, a variable can typically contain a value of any type, and the
 type of the variable may even change during the execution of the program. Under the hood, this is
 implemented through the ``zval`` struct. It is one of the most important data structures in php-src.
-It is essentially a “tagged union”, meaning it consists of an integer tag, representing the type of
+It is essentially a "tagged union", meaning it consists of an integer tag, representing the type of
 the variable, and a union for the value itself. Let's look at the value first.
 
 ************
@@ -118,7 +118,7 @@ access the same data. The ``ZEND_ENDIAN_LOHI_3`` macro is used to guarantee orde
 big- and little-endian architectures.
 
 If you're familiar with C, you'll know that the compiler likes to add padding to structures with
-“odd” sizes. It does that because the CPU can work with some offsets more efficiently that others.
+"odd" sizes. It does that because the CPU can work with some offsets more efficiently that others.
 Ignoring the ``zval.u2`` field for a second, our struct would be 12 bytes in total, 8 coming from
 ``zval.value`` and 4 from ``zval.u1``. A compiler on a 64-bit architecture will generally bump this
 to 16 bytes by adding 4 bytes of useless padding. If this padding is added anyway, we might as well

docs/source/index.rst

@@ -30,6 +30,10 @@ as various extensions that provide common functionality. This documentation is i
 understand how the interpreter works, how you can build and test changes, and how you can create
 extensions yourself.
 
+This documentation is not intended to be comprehensive, but is meant to explain core concepts that
+are not easy to grasp by reading code alone. It describes best practices, and will frequently omit
+APIs that are discouraged for general use.
+
 ******************
  How to get help?
 ******************
@@ -46,17 +50,9 @@ touch.
  Prerequisites
 ***************
 
-The php-src interpreter is written in C, and so are most of the bundled extensions. Extensions can
-also be written in C++. ext-intl is currently the only bundled extension written in C++. As such, it
-is advisable that you have *some* knowledge of C.
-
-It is also advisable to get familiar with the semantics of PHP itself, as this will help you
-determine correct behavior for bugs, and desireable behavior for new language features.
+The php-src interpreter is written in C, and so are most of the bundled extensions. While extensions
+may also be written in C++, ext-intl is currently the only bundled extension to do so. It is
+advisable that you have *some* knowledge of C before jumping into php-src.
 
-*********
- Content
-*********
-
-This documentation is not intended to be comprehensive, but is meant to explain core concepts that
-are not easy to grasp by reading code alone. It describes best practices, and will frequently omit
-APIs that are discouraged for general use.
+It is also advisable to get familiar with the semantics of PHP itself, so that you may better
+differentiate between bugs and expected behavior, and model new language features.

docs/source/introduction/high-level-overview.rst

@@ -7,21 +7,22 @@ compiled into machine-readable code ahead of time. Instead, the source files are
 interpreted when the program is executed. This can be very convenient for developers for rapid
 prototyping, as it skips a lengthy compilation phase. However, it also poses some unique challenges
 to performance, which is one of the primary reasons interpreters can be complex. php-src borrows
-many concepts from compilers and other interpreters.
+many concepts from other compilers and interpreters.
 
 **********
- Concepts
+ Pipeline
 **********
 
-The goal of the interpreter is to read the users source files from disk, and to simulate the users
-intent. This process can be split into distinct phases that are easier to understand and implement.
+The goal of the interpreter is to read the users source files, and to simulate the users intent.
+This process can be split into distinct phases that are easier to understand and implement.
 
 -  Tokenization - splitting whole source files into words, called tokens.
 -  Parsing - building a tree structure from tokens, called AST (abstract syntax tree).
--  Compilation - turning the tree structure into a list of operations, called opcodes.
+-  Compilation - traversing the AST and building a list of operations, called opcodes.
 -  Interpretation - reading and executing opcodes.
 
-php-src as a whole can be seen as a pipeline consisting of these stages.
+php-src as a whole can be seen as a pipeline consisting of these stages, using the input of the
+previous phase and producing some output for the next.
 
 .. code:: haskell
 
@@ -31,7 +32,7 @@ php-src as a whole can be seen as a pipeline consisting of these stages.
      |> compiler    -- opcodes
      |> interpreter
 
-Let's go into these phases in a bit more detail.
+Let's go into each phase in a bit more detail.
 
 **************
  Tokenization
@@ -76,97 +77,73 @@ stream of characters. The definition for PHP lives in ``Zend/zend_language_scann
 *********
 
 Parsing is the process of reading the tokens generated from the tokenizer and building a tree
-structure from it. To humans, nesting seems obvious when looking at source code, given indentation
-through whitespace and the usage of symbols like ``()`` and ``{}``. The tokens are transformed into
-a tree structure to more closely reflect the source code the way humans see it. In PHP, the AST is
-represented by generic AST nodes with a ``kind`` field. There are "normal" nodes with a
-predetermined number of children, lists with an arbitrary number of children, and
-:doc:`../core/data-structures/zval` nodes that store some underlying primitive value, like a string.
+structure from it. To humans, how source code elements are grouped seems obvious through whitespace
+and the usage of symbols like ``()`` and ``{}``. However, computers cannot visually glance over the
+code to determine these boundaries quickly. To make it easier and faster to work with, we build a
+tree structure from the tokens to more closely reflect the source code the way humans see it.
 
 Here is a simplified example of what an AST from the tokens above might look like.
 
 .. code:: text
 
-   zend_ast_list {
-       kind: ZEND_AST_IF,
-       children: 1,
-       child: [
-           zend_ast {
-               kind: ZEND_AST_IF_ELEM,
-               child: [
-                   zend_ast {
-                       kind: ZEND_AST_VAR,
-                       child: [
-                           zend_ast_zval {
-                               kind: ZEND_AST_ZVAL,
-                               zval: "cond",
-                           },
-                       ],
-                   },
-                   zend_ast_list {
-                       kind: ZEND_AST_STMT_LIST,
-                       children: 1,
-                       child: [
-                           zend_ast {
-                               kind: ZEND_AST_ECHO,
-                               child: [
-                                   zend_ast_zval {
-                                       kind: ZEND_AST_ZVAL,
-                                       zval: "Cond is true\n",
-                                   },
-                               ],
-                           },
-                       ],
-                   },
-               ],
+   ZEND_AST_IF {
+       ZEND_AST_IF_ELEM {
+           ZEND_AST_VAR {
+               ZEND_AST_ZVAL { "cond" },
            },
-       ],
+           ZEND_AST_STMT_LIST {
+               ZEND_AST_ECHO {
+                   ZEND_AST_ZVAL { "Cond is true\n" },
+               },
+           },
+       },
    }
 
-The nodes may also store additional flags in the ``attr`` field for various purposes depending on
-the node kind. They also store their original position in the source code in the ``lineno`` field.
-These fields are omitted in the example for brevity.
+Each AST node has a type and may have children. They also store their original position in the
+source code, and may define some arbitrary flags. These are omitted for brevity.
 
 Like with tokenization, we use a tool called ``Bison`` to generate the parser implementation from a
 grammar specification. The grammar lives in the ``Zend/zend_language_parser.y`` file. Check the
 `Bison documentation`_ for details. Luckily, the syntax is quite approachable.
 
 .. _bison documentation: https://www.gnu.org/software/bison/manual/
 
+Parsing is described in more detail in its `dedicated chapter <todo>`__.
+
 *************
  Compilation
 *************
 
 Computers don't understand human language, or even programming languages. They only understand
 machine code, which are sequences of simple, mostly atomic instructions for doing one thing. For
 example, they may add two numbers, load some memory from RAM, jump to an instruction under a certain
-condition, etc. It turns out that even complex expressions can be reduced to a number of these
-simple instructions.
+condition, etc. It turns out that even the most complex expressions can be reduced to a number of
+these simple instructions.
 
 PHP is a bit different, in that it does not execute machine code directly. Instead, instructions run
 on a "virtual machine", often abbreviated to VM. This is just a fancy way of saying that there is no
-physical machine that understands these instructions, but that this machine is implemented in
-software. This is our interpreter. This also means that we are free to make up instructions
-ourselves at will. Some of these instructions look very similar to something you'd find in an actual
-CPU instruction set (e.g. adding two numbers), while others are on a much higher level (e.g. load
-property of object by name).
+physical machine you can buy that understands these instructions, but that this machine is
+implemented in software. This is our interpreter. This also means that we are free to make up
+instructions ourselves at will. Some of these instructions look very similar to something you'd find
+in an actual CPU instruction set (e.g. adding two numbers), while others are much more high-level
+(e.g. load property of object by name).
 
 With that little detour out of the way, the job of the compiler is to read the AST and translate it
-into our virtual machine instructions, also called opcodes. This code lives in
-``Zend/zend_compile.c``. The compiler is invoked for each function in your program, and generates a
-list of opcodes.
+into our virtual machine instructions, also called opcodes. The code responsible for this
+transformation lives in ``Zend/zend_compile.c``. It essentially traverses the AST and generates a
+number of instructions, before going to the next node.
 
-Here's what the opcodes for the AST above might look like:
+Here's what the surprisingly compact opcodes for the AST above might look like:
 
 .. code:: text
 
    0000 JMPZ CV0($cond) 0002
    0001 ECHO string("Cond is true\n")
    0002 RETURN int(1)
 
-*************
- Interpreter
-*************
+****************
+ Interpretation
+****************
 
 Finally, the opcodes are read and executed by the interpreter. PHPs uses `three-address code`_ for
 instructions. This essentially means that each instructions may have a result value, and at most two
@@ -176,9 +153,8 @@ operands. Most modern CPUs also use this format. Both result and operands in PHP
 .. _three-address code: https://en.wikipedia.org/wiki/Three-address_code
 
 How exactly each opcode behaves depends on its purpose. You can find a complete list of opcodes in
-the generated ``Zend/zend_vm_opcodes.h`` file. The VM lives mostly in the ``Zend/zend_vm_def.h``
-file, which contains custom DSL that is expanded by ``Zend/zend_vm_gen.php`` to generate the
-``Zend/zend_vm_execute.h`` file, containing the actual VM code.
+the generated ``Zend/zend_vm_opcodes.h`` file. The behavior of each instruction is defined in
+``Zend/zend_vm_def.h``.
 
 Let's step through the opcodes form the example above:
 
@@ -193,18 +169,16 @@ Let's step through the opcodes form the example above:
 With these simple rules, we can see that the interpreter will ``echo`` only when ``$cond`` is
 truthy, and skip over the ``echo`` otherwise.
 
-That's it! This is how PHP works, fundamentally. Of course, PHP consists of many more opcodes. The
-VM is quite complex, and will be discussed separately in the `virtual machine <todo>`__ chapter.
+That's it! This is how PHP works, fundamentally. Of course, we skipped over a ton of details. The VM
+is quite complex, and will be discussed separately in the `virtual machine <todo>`__ chapter.
 
 *********
  Opcache
 *********
 
 As you may imagine, running this whole pipeline every time PHP serves a request is time consuming.
-Luckily, it is also not necessary. We can cache the opcodes in memory between requests. When a file
-is included, we can look for the file in cache, and verify via timestamp that it has not been
-modified since it was compiled. If it has not, we may reuse the opcodes from cache. This
-dramatically speeds up the execution of PHP programs. This is precisely what the opcache extension
+Luckily, it is also not necessary. We can cache the opcodes in memory between requests, to skip over
+all of the phases, except for the execution phase. This is precisely what the opcache extension
 does. It lives in the ``ext/opcache`` directory.
 
 Opcache also performs some optimizations on the opcodes before caching them. As opcaches are