From 6f8b7be05c4f876661cd71f112643971cab56b42 Mon Sep 17 00:00:00 2001 From: Mohamed Hegazy Date: Wed, 11 Nov 2015 21:58:55 -0800 Subject: [PATCH] Review comments --- Architectural-Overview.md | 37 ++++++++++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/Architectural-Overview.md b/Architectural-Overview.md index 5ff986f..b6d1c55 100644 --- a/Architectural-Overview.md +++ b/Architectural-Overview.md @@ -39,27 +39,46 @@ The language service supports the common set of a typical editor operations like ## Overview of the compilation process -The process starts with preprocessing. the preprocessor figures out what files should be included in the compilation by following references (/// references and import statements). +The process starts with preprocessing. +The preprocessor figures out what files should be included in the compilation by following references (`/// ` and `import` statements). -The parser then generates AST `Node`s. These are just abstract representation of the user input in a tree format. A `SourceFile` object represents an AST for a given file with some additional information like file name and source text. +The parser then generates AST `Node`s. +These are just an abstract representation of the user input in a tree format. +A `SourceFile` object represents an AST for a given file with some additional information like the file name and source text. -The binder then passes over the AST nodes and generates and binds `Symbol`s; these are one per named entity, each `Symbol` can have multiple `Node`s, e.g.: multiple declarations of `namespace`, or `class` and a `namespace` with the same name, etc.. the binder also handles scopes and makes sure that each symbol is created in the correct enclosing function/block scope. +The binder then passes over the AST nodes and generates and binds `Symbol`s. +One `Symbol` is created for each named entity. +There is a subtle distinction but several declaration nodes can name the same entity. +That means that sometimes different `Node`s will have the same `Symbol`, and each `Symbol` keeps track of its declaration `Node`s. +For example, a `class` and a `namespace` with the same name can *merge* and will have the same `Symbol`. +The binder also handles scopes and makes sure that each `Symbol` is created in the correct enclosing scope. Generating a `SourceFile` (along with its `Symbol`s) is done through calling the `createSourceFile` API. -So far the AST/Symbols represent the infomation of a single file. But `namespace`s for instance can span multiple files, so can interfaces, classes, etc.. so the next step is build a global view of all files in the compilation by building a `Program`. +So far, `Symbol`s represent named entities as seen within a single file, but several declarations can merge multiple files, so the next step is to build a global view of all files in the compilation by building a `Program`. -A `Program` is a collection of `SourceFile`s and a set of `CompilerOptions`. A `Program` is created by calling the `createProgram` API. +A `Program` is a collection of `SourceFile`s and a set of `CompilerOptions`. +A `Program` is created by calling the `createProgram` API. -From a `Program` instance a `TypeChecker` can be created. `TypeChecker` is the core of the TypeScript type system. it is the part responsible to figuring out relationships between `Symbols` from different file, assigning `Type`s to `Symbol`s and generating any semantic `Diagnostic`s (i.e. errors). +From a `Program` instance a `TypeChecker` can be created. +`TypeChecker` is the core of the TypeScript type system. +It is the part responsible for figuring out relationships between `Symbols` from different files, assigning `Type`s to `Symbol`s, and generating any semantic `Diagnostic`s (i.e. errors). The first thing a `TypeChecker` will do is to consolidate all the `Symbol`s from different `SourceFile`s into a single view, and build a single Symbol Table by "merging" any common `Symbol`s (e.g. `namespace`s spanning multiple files). -After initializing the original state, the `TypeChecker` is ready to answer any questions about the program. Such questions can be: what is the `Symbol` for this `Node`, or what is the `Type` of this `Symbol`, what `Symbol`s are visible at a location in the AST, or what are the `Signature`s for a function declaration, or what errors would be produced for a file. +After initializing the original state, the `TypeChecker` is ready to answer any questions about the program. +Such "questions" might be: +* What is the `Symbol` for this `Node`? +* What is the `Type` of this `Symbol`? +* What `Symbol`s are visible in this portion of the AST? +* What are the available `Signature`s for a function declaration? +* What errors should be reported for a file? -The `TypeChecker` computes everything lazely; it only "resolves" the necessary information to answer a question, the checker will only examine Nodes/Symbols/Types that contribute to the question at hand and will not attempt to examine additional entities. +The `TypeChecker` computes everything lazily; it only "resolves" the necessary information to answer a question. +The checker will only examine `Node`s/`Symbol`s/`Type`s that contribute to the question at hand and will not attempt to examine additional entities. -An `Emitter` can also be created from a given `Program`. The `Emitter` is responsible for generating the desired output for a given `SourceFile`; this includes `.js`, `.jsx`, `.d.ts`, and `.js.map` outputs. +An `Emitter` can also be created from a given `Program`. +The `Emitter` is responsible for generating the desired output for a given `SourceFile`; this includes `.js`, `.jsx`, `.d.ts`, and `.js.map` outputs. ## Terminology