doc editor review

docs/source/getstarted/quickstart.rst

@@ -113,8 +113,8 @@ give us this very easily. We can then, for example, get the header information f
 
 While this might be useful, there are two limitations here:
 
-# We can't get a reference to the ``ContractDefinition`` for Ownable (the inherited contract). In other words, we only know its name at this point but not where it comes from or what it contains.
-# We have to load each source file one at a time instead of letting SOLP discover its way through the project.
+#. We can't get a reference to the ``ContractDefinition`` for Ownable (the inherited contract). In other words, we only know its name at this point but not where it comes from or what it contains.
+#. We have to load each source file one at a time instead of letting SOLP discover its way through the project.
 
 
 Getting AST2 Nodes

docs/source/getstarted/scopes.rst

@@ -75,6 +75,8 @@ Check the parent! Qualified lookups have a base ``x``, and the member is ``y``.
 Unqualified
 ^^^^^^^^^^^
 
+In the unqualified lookup case, search the node's scope directly:
+
 .. code-block:: python
 
    symbols = ast1_node.scope.find(ast1_node.text)
@@ -124,7 +126,7 @@ Search these scopes in the same way as the previous case:
                links.append(get_symbol_link(rs))
 
 Details of ``get_symbol_link``
----------------
+------------------------------
 
 The exact details of ``get_symbol_link`` depend on what LSP framework you're using. Usually, the following info is needed
 from the reference that's found:
@@ -143,7 +145,7 @@ For Solidity built-in symbols, the ``value`` is usually ``None``, but even if it
 be a real AST1 node. SOLP doesn't parse the built-ins; they are created only in the symbol table.
 
 Checking for Built-ins
-^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^
 
 This part is simple. Check if the symbol is any of the following types:
 
@@ -157,7 +159,7 @@ This part is simple. Check if the symbol is any of the following types:
        return isinstance(sym, (symtab.BuiltinFunction, symtab.BuiltinObject, symtab.BuiltinValue))
 
 Mock Built-in File
-"""""""""""""""""
+""""""""""""""""""
 
 When the user tries to find the definition for a built-in, let's give them a file to view that contains pseudocode with
 documentation. For example, when they click on ``msg.sender``, it opens a file called builtins.sol and goes to a struct
@@ -264,7 +266,7 @@ name of this node and the range of the entire node to return to the LSP client.
 
 This function is very simple. It just copies the data from the node into the ``lsp.Range`` object. We've shown it as it
 highlights how SOLP source locations are `1 based` whereas LSP/IDE locations for this use case are `0 based`, hence the
-``-1``s on each position.
+``-1``\'s on each position.
 
 Definition Name Span
 """"""""""""""""""""

docs/source/getstarted/twoASTs.rst

@@ -50,7 +50,7 @@ Hold on! There's a couple of assumptions there. Consider the following Solidity
 There are two things to note here.
 
 1. The Parent of ``toUint256`` Is a ``LibraryDefinition``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This point is solved by changing our mental model slightly. Does it really matter that the parent is a library or a contract?
 Usually, not really. Instead, we generalize the parent of something like a function or a state variable to be a TopLevelUnit in AST2.
@@ -76,8 +76,8 @@ Solidity allows free-floating definitions for functions and events as well as ne
 inside of a contract). This makes traversing AST1 nodes more difficult as you don't have a guarantee that the SourceUnit
 is a root node or if it is part of another SourceUnit.
 
-2. FileDefinitions
-^^^^^^^^^^^^^^^^^^^
+2. FileDefinitions Can Contain ContractParts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Ask the virtual file system to load and parse the file above. You'll get a list of source units:
 
@@ -119,7 +119,7 @@ These constructs in Solidity require compiler support for the Solidity code to m
 
 * Imports need to be resolved using path resolution rules.
 * Pragmas influence the compiler version.
-* Using statements change what members are available for a type in a given scope.
+* Using statements change which members are available for a type in a given scope.
 
 These are complicated details that aren't useful to most people who need to the use the AST; they just want to deal
 with a simple AST interface that lets them easily navigate the Solidity code.

docs/source/getstarted/vfshooks.rst

@@ -66,3 +66,8 @@ custom parsers, create a shim for :py:meth:`_add_loaded_source <solidity_parser.
 
 .. note:: The creator has to have the same signature as ``make_ast``.
 
+Conclusion
+----------
+For most users the contents of this guide are never needed as initializer arguments are capable of changing the file
+loading and parser selection characteristics automatically. However, for completeness, this guide has given some common
+techniques for extending and customising the behaviour of the VirtualFileSystem