From de3470190c00d2e5f76b387b3e8a0797614e4737 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Wed, 28 Feb 2018 10:40:30 -0500 Subject: [PATCH] Proofreading the docs - very minor changes! --- doc/0_Introduction.markdown | 4 ++-- doc/2_Usage_of_basic_components.markdown | 10 +++++----- doc/component/AST_builders.markdown | 2 +- doc/component/Error_handling.markdown | 2 +- doc/component/Lexer.markdown | 6 +++--- doc/component/Pretty_printing.markdown | 6 +++--- 6 files changed, 15 insertions(+), 15 deletions(-) diff --git a/doc/0_Introduction.markdown b/doc/0_Introduction.markdown index c3cd4e5..240f7fd 100644 --- a/doc/0_Introduction.markdown +++ b/doc/0_Introduction.markdown @@ -14,7 +14,7 @@ There are other ways of processing source code. One that PHP supports natively i token stream generated by [`token_get_all`][2]. The token stream is much more low level than the AST and thus has different applications: It allows to also analyze the exact formatting of a file. On the other hand the token stream is much harder to deal with for more complex analysis. -For example an AST abstracts away the fact that in PHP variables can be written as `$foo`, but also +For example, an AST abstracts away the fact that, in PHP, variables can be written as `$foo`, but also as `$$bar`, `${'foobar'}` or even `${!${''}=barfoo()}`. You don't have to worry about recognizing all the different syntaxes from a stream of tokens. @@ -36,7 +36,7 @@ hacky and not perfect, but it should work well on any sane code. What output does it produce? ---------------------------- -The parser produces an [Abstract Syntax Tree][1] (AST) also known as a node tree. How this looks like +The parser produces an [Abstract Syntax Tree][1] (AST) also known as a node tree. How this looks can best be seen in an example. The program `parse()`, then changed and then again converted to code using `PhpParser\PrettyPrinter\Standard->prettyPrint()`. @@ -351,7 +351,7 @@ class, which will define empty default implementations for all the above methods The NameResolver node visitor ----------------------------- -One visitor is already bundled with the package: `PhpParser\NodeVisitor\NameResolver`. This visitor +One visitor that is already bundled with the package is `PhpParser\NodeVisitor\NameResolver`. This visitor helps you work with namespaced code by trying to resolve most names to fully qualified ones. For example, consider the following code: @@ -362,7 +362,7 @@ For example, consider the following code: In order to know that `B\C` really is `A\C` you would need to track aliases and namespaces yourself. The `NameResolver` takes care of that and resolves names as far as possible. -After running it most names will be fully qualified. The only names that will stay unqualified are +After running it, most names will be fully qualified. The only names that will stay unqualified are unqualified function and constant names. These are resolved at runtime and thus the visitor can't know which function they are referring to. In most cases this is a non-issue as the global functions are meant. diff --git a/doc/component/AST_builders.markdown b/doc/component/AST_builders.markdown index e0fd8e2..0e32873 100644 --- a/doc/component/AST_builders.markdown +++ b/doc/component/AST_builders.markdown @@ -1,7 +1,7 @@ AST builders ============ -When PHP-Parser is used to generate (or modify) code, by first creating an Abstract Syntax Tree and +When PHP-Parser is used to generate (or modify) code by first creating an Abstract Syntax Tree and then using the [pretty printer](Pretty_printing.markdown) to convert it to PHP code, it can often be tedious to manually construct AST nodes. The project provides a number of utilities to simplify the construction of common AST nodes. diff --git a/doc/component/Error_handling.markdown b/doc/component/Error_handling.markdown index c1579e9..55bb515 100644 --- a/doc/component/Error_handling.markdown +++ b/doc/component/Error_handling.markdown @@ -27,7 +27,7 @@ try { } ``` -Before using column information its availability needs to be checked with `$e->hasColumnInfo()`, as the precise +Before using column information, its availability needs to be checked with `$e->hasColumnInfo()`, as the precise location of an error cannot always be determined. The methods for retrieving column information also have to be passed the source code of the parsed file. An example for printing an error: diff --git a/doc/component/Lexer.markdown b/doc/component/Lexer.markdown index 399c92b..be26e38 100644 --- a/doc/component/Lexer.markdown +++ b/doc/component/Lexer.markdown @@ -107,9 +107,9 @@ function handleHaltCompiler(): string; function getNextToken(string &$value = null, array &$startAttributes = null, array &$endAttributes = null): int; ``` -The `startLexing()` method is invoked with the source code that is to be lexed (including the opening tag) whenever the -`parse()` method of the parser is called. It can be used to reset state or preprocess the source code or tokens. The -passes `ErrorHandler` should be used to report lexing errors. +The `startLexing()` method is invoked whenever the `parse()` method of the parser is called and is passed the source +code that is to be lexed (including the opening tag). It can be used to reset state or preprocess the source code or tokens. The +passed `ErrorHandler` should be used to report lexing errors. The `getTokens()` method returns the current token array, in the usual `token_get_all()` format. This method is not used by the parser (which uses `getNextToken()`), but is useful in combination with the token position attributes. diff --git a/doc/component/Pretty_printing.markdown b/doc/component/Pretty_printing.markdown index 40c35e6..d6198e3 100644 --- a/doc/component/Pretty_printing.markdown +++ b/doc/component/Pretty_printing.markdown @@ -52,8 +52,8 @@ For automated code refactoring, migration and similar, you will usually only wan portion of the code and leave the remainder alone. The basic pretty printer is not suitable for this, because it will also reformat parts of the code which have not been modified. -Since PHP-Parser 4.0 an experimental formatting-preserving pretty-printing mode is available, which -attempts to preserve the formatting of code, those AST nodes have not changed, and only reformat +Since PHP-Parser 4.0, an experimental formatting-preserving pretty-printing mode is available, which +attempts to preserve the formatting of code (those AST nodes that have not changed) and only reformat code which has been modified or newly inserted. Use of the formatting-preservation functionality requires some additional preparatory steps: @@ -86,7 +86,7 @@ $newCode = $printer->printFormatPreserving($newStmts, $oldStmts, $oldTokens); ``` If you make use of the name resolution functionality, you will likely want to disable the -`replaceNames` option. This will add resolved names as attributes, instead of directlying modifying +`replaceNodes` option. This will add resolved names as attributes, instead of directlying modifying the AST and causing spurious changes to the pretty printed code. For more information, see the [name resolution documentation](Name_resolution.markdown).