Merge #96

96: [WIP] Begin to add some contributing docs (#95) r=matklad a=DJMcNab

Currently adds some documentation about `cargo gen-kinds`.

Note that I am unsure of some of the details, such as why `DOT` is in `multi_byte_tokens`, hence the [WIP] tag.

Based on #95.

Co-authored-by: Daniel McNab <[email protected]>

5 files changed, 20 insertions, 1 deletions

diff --git a/crates/ra_syntax/src/ast/generated.rs b/crates/ra_syntax/src/ast/generated.rs
index c945c094a..2db6dff1b 100644
--- a/crates/ra_syntax/src/ast/generated.rs
+++ b/crates/ra_syntax/src/ast/generated.rs
@@ -1,3 +1,6 @@
+// This file is automatically generated based on the file `./generated.rs.tera` when `cargo gen-kinds` is run
+// Do not edit manually
+
 use {
     ast,
     SyntaxNodeRef, AstNode,
diff --git a/crates/ra_syntax/src/ast/generated.rs.tera b/crates/ra_syntax/src/ast/generated.rs.tera
index a72e9b732..ceb2cd7e2 100644
--- a/crates/ra_syntax/src/ast/generated.rs.tera
+++ b/crates/ra_syntax/src/ast/generated.rs.tera
@@ -1,3 +1,8 @@
+{# THIS File is not automatically generated:
+the below applies to the result of this template
+#}// This file is automatically generated based on the file `./generated.rs.tera` when `cargo gen-kinds` is run
+// Do not edit manually
+
 use {
     ast,
     SyntaxNodeRef, AstNode,
diff --git a/crates/ra_syntax/src/grammar.ron b/crates/ra_syntax/src/grammar.ron
index 77ae4c7db..4b990fd8d 100644
--- a/crates/ra_syntax/src/grammar.ron
+++ b/crates/ra_syntax/src/grammar.ron
@@ -1,3 +1,5 @@
+// Stores definitions which must be used in multiple places
+// See `cargo gen-kinds` (defined in crates/tools/src/main.rs)
 Grammar(
     single_byte_tokens: [
         [";", "SEMI"],
@@ -23,8 +25,9 @@ Grammar(
         ["^", "CARET"],
         ["%", "PERCENT"],
     ],
+    // TODO: Confirm surmision: the tokens which cannot be recorded in a single UTF-8 byte
     multi_byte_tokens: [
-        [".", "DOT"],
+        [".", "DOT"], // Note: DOT is here because <TODO: REASON>
         ["..", "DOTDOT"],
         ["...", "DOTDOTDOT"],
         ["..=", "DOTDOTEQ"],
diff --git a/crates/ra_syntax/src/syntax_kinds/generated.rs b/crates/ra_syntax/src/syntax_kinds/generated.rs
index 7882bded9..11e9150bb 100644
--- a/crates/ra_syntax/src/syntax_kinds/generated.rs
+++ b/crates/ra_syntax/src/syntax_kinds/generated.rs
@@ -1,3 +1,6 @@
+// This file is automatically generated based on the file `./generated.rs.tera` when `cargo gen-kinds` is run
+// Do not edit manually
+
 #![allow(bad_style, missing_docs, unreachable_pub)]
 #![cfg_attr(rustfmt, rustfmt_skip)]
 use super::SyntaxInfo;
diff --git a/crates/ra_syntax/src/syntax_kinds/generated.rs.tera b/crates/ra_syntax/src/syntax_kinds/generated.rs.tera
index 90618721a..018564b8a 100644
--- a/crates/ra_syntax/src/syntax_kinds/generated.rs.tera
+++ b/crates/ra_syntax/src/syntax_kinds/generated.rs.tera
@@ -1,3 +1,8 @@
+{# THIS File is not automatically generated:
+the below applies to the result of this template
+#}// This file is automatically generated based on the file `./generated.rs.tera` when `cargo gen-kinds` is run
+// Do not edit manually
+
 #![allow(bad_style, missing_docs, unreachable_pub)]
 #![cfg_attr(rustfmt, rustfmt_skip)]
 use super::SyntaxInfo;