Final edits

Author: lucic71

docs/src/rules/format.md

@@ -70,7 +70,7 @@ template <typename T1> using t1 = std::vector<T1>;
 ```rust
 // rules/vector/tgt_unsafe.rs
 fn t1<T1>() -> Vec<T1> {
-    Default::default()
+    Vec::new()
 }
 ```
 

docs/src/rules/ir.md

@@ -64,7 +64,7 @@ The fragment kinds are:
   [Rule Rewriting](./rewriting.md)).
 * `va_args`: the expansion point for a variadic tail.
 
-Every type in the IR (in `params`, `return_type`, and type rules) is a
+Every type in the Rules IR (in `params`, `return_type`, and type rules) is a
 `TypeInfo` object, the type text plus a set of flags:
 
 * `is_refcount_pointer`: the type is a `Ptr<...>`.
@@ -83,7 +83,7 @@ An `ExprRule` carries two flags of its own:
 * `is_extern`: the rule is an extern passthrough declaration and has no
   body.
 
-Fields that are false, empty, or unset are omitted from the JSON. A `va`
+Fields that are false, empty, or unset are omitted from the Rules IR. A `va`
 parameter is never listed in `params`, and a `()` return type is omitted.
 
 A type rule serializes as a `TypeRule` object: its `TypeInfo` plus the
@@ -98,28 +98,35 @@ There is no explicit tag distinguishing the two rule kinds: an entry with
 
 ## In-memory form
 
-`cpp2rust` mirrors this JSON in C++ structs of the same names, defined in
-`cpp2rust/converter/translation_rule.h`. `TranslationRule::Load` reads one
+`cpp2rust` mirrors the Rules IR in C++ structs of the same names, defined in
+[`cpp2rust/converter/translation_rule.h`][translation-rule-h].
+`TranslationRule::Load` reads one
 module directory (the `ir_*.json` files described above) and produces two
-maps keyed by rule name, one holding `ExprRule`s and one holding `TypeRule`s:
+maps keyed by rule name, one holding [`ExprRule`]s and one holding
+[`TypeRule`]s:
+
+[translation-rule-h]: https://github.com/cpp2rust/cpp2rust/blob/master/cpp2rust/converter/translation_rule.h
+[`ExprRule`]: https://github.com/cpp2rust/cpp2rust/blob/master/cpp2rust/converter/translation_rule.h#L71
+[`TypeRule`]: https://github.com/cpp2rust/cpp2rust/blob/master/cpp2rust/converter/translation_rule.h#L84
 
 * An `ExprRule` holds the body
   [fragments](#target-ir-ir_unsafejson--ir_refcountjson), the parameter and
-  return `TypeInfo`s, and the two rule-level flags. The name-keyed JSON maps become
+  return `TypeInfo`s, and the two rule-level flags (`multi_statement` and `is_extern`). The
+  name-keyed Rules IR maps become
   positional vectors: parameter `aN` is entry N of `params`, generic `TN` is
   entry N-1 of `generics` (each entry being the bound list). Rules support
   at most 9 generic parameters (`kMaxGenerics`).
 * A `TypeRule` holds the mapped type's `TypeInfo` and the `initializer`
   expression. The same struct also represents the built-in type mappings
   (scalars, pointers, ...) that the loader registers directly in code,
-  without any JSON behind them: for example, `int` maps to `i32`, and
+  without any Rules IR behind them: for example, `int` maps to `i32`, and
   `int *` to `*mut i32` in the unsafe model or `Ptr<i32>` in the refcount
   model.
 
 Both also carry `src`, the canonical C++ signature attached from
 [`ir_src.json`](#source-ir-ir_srcjson); it is the key the rule is matched
 by.
 
-How the loader finds the IR directory, overlays the refcount model on the
+How the loader finds the Rules IR directory, overlays the refcount model on the
 unsafe one, and indexes the loaded rules for matching is covered in
 [Loading and Matching](./loading.md).

docs/src/rules/loading.md

@@ -2,12 +2,12 @@
 
 ## Finding the rules directory
 
-`cpp2rust` takes the IR directory via `--rules <dir>`. If the flag is omitted
+`cpp2rust` takes the Rules IR directory via `--rules <dir>`. If the flag is omitted
 it tries `./rules` and then `<executable dir>/../rules`, accepting the first
 candidate that contains (recursively) a subdirectory with `ir_src.json` plus
-`ir_unsafe.json` or `ir_refcount.json`. Since the build writes the IR to
+`ir_unsafe.json` or `ir_refcount.json`. Since the build writes the Rules IR to
 `<build>/rules` and the binary lands in `<build>/bin`, the default resolution
-picks up the generated IR without any flags.
+picks up the generated Rules IR without any flags.
 
 ## Loading
 
@@ -51,7 +51,7 @@ same canonical printer used by `cpp-rule-preprocessor`, which is what makes
 the two sides comparable:
 
 * Functions and methods print as
-  `<return type> <qualified name>(<param types>)[ const][ &|&&]`.
+  `<return type> <qualified::name>(<param types>[, ...])[ const][ volatile][ &|&&]`.
 * Enum constants and global variables print as their qualified name.
 * Integer literals expanded from a macro print as the macro name.
 

docs/src/rules/overview.md

@@ -5,30 +5,25 @@ Each rule module lives in the `rules/` directory and pairs a C++ source file
 (`src.cpp`) with its Rust translation for each model (`tgt_unsafe.rs` and
 `tgt_refcount.rs`).
 
-The central idea is that every rule is expressed as ordinary, compilable
-C++ and Rust source code, free of anything platform dependent. Both sides are
-run through real compilers at build time, so a rule that does not compile
-fails the build, and the platform-specific spellings a rule needs to match
-against (for example `bool` canonicalizing to `_Bool`) are derived by the
-compiler on the host rather than written by hand. The same rule sources work
-on every platform `cpp2rust` builds on.
+Every rule is expressed as ordinary, compilable C++ and Rust source code,
+free of anything platform dependent. Both sides are run through real
+compilers at build time, so a rule that does not compile fails the build, and
+the platform-specific spellings (for example `bool` canonicalizing to
+`_Bool`) are derived by the compiler on the host rather than written by hand.
+The same rule sources work on every platform `cpp2rust` builds on.
 
 Rules go through a build-time compilation pipeline before `cpp2rust` can use
 them:
 
 1. You author a rule module: C++ patterns in `src.cpp` and Rust targets in
    `tgt_unsafe.rs` / `tgt_refcount.rs`.
-2. At build time, two preprocessors compile the module into JSON IR under
+2. At build time, two preprocessors compile the module into Rules IR under
    `<build>/rules/<module>/`:
    `cpp-rule-preprocessor` compiles the C++ side into `ir_src.json`, and
    `rule-preprocessor` compiles the Rust side into `ir_unsafe.json` and
    `ir_refcount.json`.
-3. At startup, `cpp2rust` loads the IR files and indexes the rules by the
+3. At startup, `cpp2rust` loads the Rules IR files and indexes the rules by the
    canonical signature of the C++ construct they match.
-4. During translation, the converter looks up rules by signature and splices
-   their Rust bodies into the output, substituting arguments for placeholders
-   and rewriting the body when needed (e.g. wrapping method calls in
-   `with_mut` when the receiver is a `Ptr<T>`).
 
 The rest of this part covers each stage:
 
@@ -41,9 +36,9 @@ The rest of this part covers each stage:
 * [Conventions](./conventions.md): naming and style conventions rule authors
   must follow.
 * [The Rule Preprocessors](./preprocessors.md): the two build-time tools that
-  compile rules to IR.
+  compile rules to the Rules IR.
 * [The Rules IR](./ir.md): the JSON format the preprocessors emit.
-* [Loading and Matching](./loading.md): how `cpp2rust` loads the IR and
+* [Loading and Matching](./loading.md): how `cpp2rust` loads the Rules IR and
   matches rules against the input AST.
 * [The Matching Engine](./matching.md): how a candidate rule's signature
   is unified against the input.

docs/src/rules/preprocessors.md

@@ -1,6 +1,6 @@
 # The Rule Preprocessors
 
-Two build-time tools compile rule modules into the [JSON IR](./ir.md) that
+Two build-time tools compile rule modules into the [Rules IR](./ir.md) that
 `cpp2rust` loads at runtime. Both write into `<build>/rules/<module>/`:
 
 * `cpp-rule-preprocessor` compiles `src.cpp`/`src.c` into `ir_src.json`.