Improve documentation

CONTRIBUTING.md

@@ -34,14 +34,36 @@ pretty-print those errors, but will not attempt to construct the ASG.
 Otherwise the ASG will be constructed, and any *semantic* errors found will be
 printed.
 
-### Continuous Integration (CI)
+### Testing and Continuous Integration (CI)
+
+> [!IMPORTANT]
+> Don't run tests with `cargo test`. Rather use [./run_tests.sh](./run_tests.sh).
+> Or run the command contained therein:
+>
+> `cargo test --lib --tests -- --skip sourcegen_ast --skip sourcegen_ast_nodes`
 
 All pull requests must pass a CI check before being merged. You can check if CI will pass locally with
 ```shell
 cargo fmt --all -- --check && cargo build --verbose && cargo clippy -- -D warnings && cargo test --verbose -- --skip sourcegen_ast --skip sourcegen_ast_nodes
 ```
+A script for checking CI locally is [./local_CI.sh](./local_CI.sh)
 
 ### Clippy
 
 One of the CI items is `cargo clippy`.
 To handle a lot of errors at the command line you can use (for unix-like OS) `cargo clippy --color always &| less -R`.
+
+### Modifying the ungrammar
+
+An ["ungrammar"](https://docs.rs/ungrammar/latest/ungrammar/) (and [here](https://github.com/rust-analyzer/ungrammar)) describes a concrete syntax tree.
+
+An ungrammar for OpenQASM 3 is
+in [./crates/oq3_syntax/openqasm3.ungram](./crates/oq3_syntax/openqasm3.ungram).
+For most work, it need not be edited.
+If the file is modified,
+three source files must be regenerated:
+* [./crates/oq3_parser/src/syntax_kind/syntax_kind_enum.rs](./crates/oq3_parser/src/syntax_kind/syntax_kind_enum.rs)
+* [./crates/oq3_syntax/src/ast/generated/nodes.rs](./crates/oq3_syntax/src/ast/generated/nodes.rs)
+* [./crates/oq3_syntax/src/ast/generated/tokens.rs](./crates/oq3_syntax/src/ast/generated/tokens.rs)
+
+For further information, see [./codegen_scripts/README.md](./codegen_scripts/README.md)

codegen_scripts/README.md

@@ -1,16 +1,27 @@
 ## Code generation for the crate oq3_syntax
 
+### Do I need to run code generation?
+
+If you don't modify the "ungrammar" [./crates/oq3_syntax/openqasm3.ungram](./crates/oq3_syntax/openqasm3.ungram)
+then you don't need to generate any code to build or develop openqasm_parser, and you can stop reading here.
+
+If you *do* modify [./crates/oq3_syntax/openqasm3.ungram](./crates/oq3_syntax/openqasm3.ungram), then read on.
+
 NOTE: These (rather simple) scripts controlling codegen have been developed under fedora linux. They may need
 to be modified for your OS. The codegen itself is done in rust and should run correctly on most
 platforms, or should be easily made to do so.
 
 The source files in [../crates/oq3_syntax/src/ast/generated](../crates/oq3_syntax/src/ast/generated) are generated via scripts
-run during development. They do not need to be run when building the crates if the input
-files to the codegen have not been modified.
+that are run during development.
+They do not need to be run when building the crates if the input files to the codegen have not been modified.
 
 On the other hand, if the input files to codegen have been modified, then codegen scripts
-must be run by hand. Some details are in [./mkgenerated](./mkgenerated).
+must be run by calling [./mkgenerated](./mkgenerated). See comments in [./mkgenerated](./mkgenerated).
 
-Run ./mkgenerated to write generated rust source to temporary files.
+Run ./mkgenerated from this directory to write generated rust source to temporary files.
+Trying to run ./mkgenerated from the root of this repo will fail to generate the required code.
 Run [./cpnodes.sh](./cpnodes.sh) and [./cpgenerated.sh](./cpgenerated.sh) to overwrite the revision-controlled source
 files with the temporary files.
+
+> [!IMPORTANT]
+> [./mkgenerated](./mkgenerated) runs [./mk_nodes.sh](./mk_nodes.sh) twice. The first time errors are reported such as: `test tests::sourcegen_ast::write_syntax_kinds_enum ... FAILED`. These errors can be ignored. The second time [./mk_nodes.sh](./mk_nodes.sh) runs no errors should be reported.

crates/oq3_syntax/openqasm3.ungram

@@ -16,11 +16,11 @@
 
 // Notes for OQ3
 //
-// Introducing a literal keyword that is also a legal rust identifer here is not difficult, but easy, just do it.
+// Introducing a literal keyword that is also a legal OQ3 identifer here is not difficult, but easy; just do it.
 // 'measure' below requires that the literal "measure" is present.
 //
 // However '++' takes more work.
-// If you introduce a literal that cannot start a rust identifier, say `++`:
+// If you introduce a literal that cannot start an OQ3 identifier, say `++`:
 //  1. Map it to an identifer in `fn method_name` in sourcegen_ast.rs. For example:
 //   `"++" => "double_plus"`
 //  2. Add ++ to KINDS_SRC in ast_src.rs