From 32cc25597af3cc93b7803f2a9f1317adf24e0078 Mon Sep 17 00:00:00 2001 From: John Lapeyre Date: Sat, 13 Jan 2024 17:27:29 -0500 Subject: [PATCH] Update docs and comments to reflect reorg and rename of code --- NOTICE.txt | 2 +- README.md | 13 ++++--------- crates/oq3_syntax/src/ast/make.rs | 2 +- 3 files changed, 6 insertions(+), 11 deletions(-) diff --git a/NOTICE.txt b/NOTICE.txt index c587c86..a7c65d2 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -1,4 +1,4 @@ -The code in crates `lexer`, `parser`, and `oq3_syntax` are derived +The code in crates `oq3_lexer`, `oq3_parser`, and `oq3_syntax` are derived from crates in the rust-analyzer project, commit (d398a). The code in these crates is licensed in this OpenQASM 3 parser project under the following MIT license: diff --git a/README.md b/README.md index 7291d78..8373ddb 100644 --- a/README.md +++ b/README.md @@ -29,23 +29,18 @@ For instance, I hope to soon replace "I" with "we". The first three crates are based on tools for `rust` and `rust-analyzer`. * [oq3_lexer](./crates/oq3_lexer) -- A lightly modified version of the `rustc` (the rust compiler) lexer. -* [oq3_parser](./crates/oq3_parser) -- Ingests output of `lexer` and outputs a concrete syntax tree. -* [oq3_syntax](./crates/oq3_syntax) -- Ingests output of `parser` and outputs an abstract syntax tree (AST). +* [oq3_parser](./crates/oq3_parser) -- Ingests output of `oq3_lexer` and outputs a concrete syntax tree. +* [oq3_syntax](./crates/oq3_syntax) -- Ingests output of `oq3_parser` and outputs an abstract syntax tree (AST). The rust-analyzer [documentation](#design) sometimes refers to this AST by something like "typed AST". This can be confusing. It does not mean that semantic analysis has been performed and OQ3 types have been assigned to all expressions. It means that the rust type system is used to encode syntactic elements, in contrast to some lower representations in the same crate. -* [semantics](./crates/oq3_semantics) -- Performs [semantic analysis](https://en.wikipedia.org/wiki/Compiler#Front_end) +* [oq3_semantics](./crates/oq3_semantics) -- Performs [semantic analysis](https://en.wikipedia.org/wiki/Compiler#Front_end) and outputs an [abstract semantic graph (ASG)](https://en.wikipedia.org/wiki/Abstract_semantic_graph) There are other names for this structure. But "ASG" is convenient. -* [source_file](./crates/oq3_source_file) -- A higher-level interface to the syntactic AST. This sits beetween the syntactic AST and +* [oq3_source_file](./crates/oq3_source_file) -- A higher-level interface to the syntactic AST. This sits beetween the syntactic AST and semantic ASG. This crate manages the main source file and incuded source files. -#### Supporting crates - -* [sourcegen](./crates/oq3_sourcegen) -- supports code generation. This is a very small crate that is copied here because the external -crate has a bug. - ### Warning ! Do not run `cargo test`. Rather use `./run_tests.sh` or commands found therein. This is because codegen is implemented via diff --git a/crates/oq3_syntax/src/ast/make.rs b/crates/oq3_syntax/src/ast/make.rs index 160b54a..b6ede97 100644 --- a/crates/oq3_syntax/src/ast/make.rs +++ b/crates/oq3_syntax/src/ast/make.rs @@ -9,7 +9,7 @@ //! smarter than that, it belongs to the `ext` submodule. //! //! GJL: I think these are meant to be used at a higher level, ie HIR. Not used within -//! the lexer and parser crates. +//! the oq3_lexer and oq3_parser crates. //! //! Keep in mind that `from_text` functions should be kept private. The public //! API should require to assemble every node piecewise. The trick of