Merge #256

256: Improve/add use_item documentation r=matklad a=DJMcNab

Adds some documentation to use_item explaining all code paths (use imports are hard, especially with the ongoing discussion of anchored v. uniform paths - see https://github.com/rust-lang/rust/issues/55618 for what appears to be the latest developments)

Co-authored-by: DJMcNab <[email protected]>

10 files changed, 413 insertions, 0 deletions

diff --git a/crates/ra_syntax/tests/data/parser/inline/0114_use_path.rs b/crates/ra_syntax/tests/data/parser/inline/0114_use_path.rs
new file mode 100644
index 000000000..328e94736
--- /dev/null
+++ b/crates/ra_syntax/tests/data/parser/inline/0114_use_path.rs
@@ -0,0 +1,3 @@
+use ::crate_name; // Rust 2018 - All flavours
+use crate_name; // Rust 2018 - Anchored paths
+use item_in_scope_or_crate_name; // Rust 2018 - Uniform Paths
diff --git a/crates/ra_syntax/tests/data/parser/inline/0114_use_path.txt b/crates/ra_syntax/tests/data/parser/inline/0114_use_path.txt
new file mode 100644
index 000000000..420449e61
--- /dev/null
+++ b/crates/ra_syntax/tests/data/parser/inline/0114_use_path.txt
@@ -0,0 +1,38 @@
+SOURCE_FILE@[0; 154)
+  USE_ITEM@[0; 17)
+    USE_KW@[0; 3)
+    WHITESPACE@[3; 4)
+    USE_TREE@[4; 16)
+      PATH@[4; 16)
+        PATH_SEGMENT@[4; 16)
+          COLONCOLON@[4; 6)
+          NAME_REF@[6; 16)
+            IDENT@[6; 16) "crate_name"
+    SEMI@[16; 17)
+  WHITESPACE@[17; 18)
+  COMMENT@[18; 45)
+  WHITESPACE@[45; 46)
+  USE_ITEM@[46; 61)
+    USE_KW@[46; 49)
+    WHITESPACE@[49; 50)
+    USE_TREE@[50; 60)
+      PATH@[50; 60)
+        PATH_SEGMENT@[50; 60)
+          NAME_REF@[50; 60)
+            IDENT@[50; 60) "crate_name"
+    SEMI@[60; 61)
+  WHITESPACE@[61; 62)
+  COMMENT@[62; 91)
+  WHITESPACE@[91; 92)
+  USE_ITEM@[92; 124)
+    USE_KW@[92; 95)
+    WHITESPACE@[95; 96)
+    USE_TREE@[96; 123)
+      PATH@[96; 123)
+        PATH_SEGMENT@[96; 123)
+          NAME_REF@[96; 123)
+            IDENT@[96; 123) "item_in_scope_or_crate_name"
+    SEMI@[123; 124)
+  WHITESPACE@[124; 125)
+  COMMENT@[125; 153)
+  WHITESPACE@[153; 154)
diff --git a/crates/ra_syntax/tests/data/parser/inline/0115_use_alias.rs b/crates/ra_syntax/tests/data/parser/inline/0115_use_alias.rs
new file mode 100644
index 000000000..c7a141bbd
--- /dev/null
+++ b/crates/ra_syntax/tests/data/parser/inline/0115_use_alias.rs
@@ -0,0 +1,7 @@
+use some::path as some_name;
+use some::{
+ other::path as some_other_name,
+ different::path as different_name,
+ yet::another::path,
+ running::out::of::synonyms::for::different::*
+};
diff --git a/crates/ra_syntax/tests/data/parser/inline/0115_use_alias.txt b/crates/ra_syntax/tests/data/parser/inline/0115_use_alias.txt
new file mode 100644
index 000000000..f7b599476
--- /dev/null
+++ b/crates/ra_syntax/tests/data/parser/inline/0115_use_alias.txt
@@ -0,0 +1,124 @@
+SOURCE_FILE@[0; 181)
+  USE_ITEM@[0; 28)
+    USE_KW@[0; 3)
+    WHITESPACE@[3; 4)
+    USE_TREE@[4; 27)
+      PATH@[4; 14)
+        PATH@[4; 8)
+          PATH_SEGMENT@[4; 8)
+            NAME_REF@[4; 8)
+              IDENT@[4; 8) "some"
+        COLONCOLON@[8; 10)
+        PATH_SEGMENT@[10; 14)
+          NAME_REF@[10; 14)
+            IDENT@[10; 14) "path"
+      WHITESPACE@[14; 15)
+      ALIAS@[15; 27)
+        AS_KW@[15; 17)
+        WHITESPACE@[17; 18)
+        NAME@[18; 27)
+          IDENT@[18; 27) "some_name"
+    SEMI@[27; 28)
+  WHITESPACE@[28; 29)
+  USE_ITEM@[29; 180)
+    USE_KW@[29; 32)
+    WHITESPACE@[32; 33)
+    USE_TREE@[33; 179)
+      PATH@[33; 37)
+        PATH_SEGMENT@[33; 37)
+          NAME_REF@[33; 37)
+            IDENT@[33; 37) "some"
+      COLONCOLON@[37; 39)
+      USE_TREE_LIST@[39; 179)
+        L_CURLY@[39; 40)
+        WHITESPACE@[40; 42)
+        USE_TREE@[42; 72)
+          PATH@[42; 53)
+            PATH@[42; 47)
+              PATH_SEGMENT@[42; 47)
+                NAME_REF@[42; 47)
+                  IDENT@[42; 47) "other"
+            COLONCOLON@[47; 49)
+            PATH_SEGMENT@[49; 53)
+              NAME_REF@[49; 53)
+                IDENT@[49; 53) "path"
+          WHITESPACE@[53; 54)
+          ALIAS@[54; 72)
+            AS_KW@[54; 56)
+            WHITESPACE@[56; 57)
+            NAME@[57; 72)
+              IDENT@[57; 72) "some_other_name"
+        COMMA@[72; 73)
+        WHITESPACE@[73; 75)
+        USE_TREE@[75; 108)
+          PATH@[75; 90)
+            PATH@[75; 84)
+              PATH_SEGMENT@[75; 84)
+                NAME_REF@[75; 84)
+                  IDENT@[75; 84) "different"
+            COLONCOLON@[84; 86)
+            PATH_SEGMENT@[86; 90)
+              NAME_REF@[86; 90)
+                IDENT@[86; 90) "path"
+          WHITESPACE@[90; 91)
+          ALIAS@[91; 108)
+            AS_KW@[91; 93)
+            WHITESPACE@[93; 94)
+            NAME@[94; 108)
+              IDENT@[94; 108) "different_name"
+        COMMA@[108; 109)
+        WHITESPACE@[109; 111)
+        USE_TREE@[111; 129)
+          PATH@[111; 129)
+            PATH@[111; 123)
+              PATH@[111; 114)
+                PATH_SEGMENT@[111; 114)
+                  NAME_REF@[111; 114)
+                    IDENT@[111; 114) "yet"
+              COLONCOLON@[114; 116)
+              PATH_SEGMENT@[116; 123)
+                NAME_REF@[116; 123)
+                  IDENT@[116; 123) "another"
+            COLONCOLON@[123; 125)
+            PATH_SEGMENT@[125; 129)
+              NAME_REF@[125; 129)
+                IDENT@[125; 129) "path"
+        COMMA@[129; 130)
+        WHITESPACE@[130; 132)
+        USE_TREE@[132; 177)
+          PATH@[132; 174)
+            PATH@[132; 163)
+              PATH@[132; 158)
+                PATH@[132; 148)
+                  PATH@[132; 144)
+                    PATH@[132; 139)
+                      PATH_SEGMENT@[132; 139)
+                        NAME_REF@[132; 139)
+                          IDENT@[132; 139) "running"
+                    COLONCOLON@[139; 141)
+                    PATH_SEGMENT@[141; 144)
+                      NAME_REF@[141; 144)
+                        IDENT@[141; 144) "out"
+                  COLONCOLON@[144; 146)
+                  PATH_SEGMENT@[146; 148)
+                    NAME_REF@[146; 148)
+                      IDENT@[146; 148) "of"
+                COLONCOLON@[148; 150)
+                PATH_SEGMENT@[150; 158)
+                  NAME_REF@[150; 158)
+                    IDENT@[150; 158) "synonyms"
+              COLONCOLON@[158; 160)
+              err: `expected identifier`
+              PATH_SEGMENT@[160; 163)
+                ERROR@[160; 163)
+                  FOR_KW@[160; 163)
+            COLONCOLON@[163; 165)
+            PATH_SEGMENT@[165; 174)
+              NAME_REF@[165; 174)
+                IDENT@[165; 174) "different"
+          COLONCOLON@[174; 176)
+          STAR@[176; 177)
+        WHITESPACE@[177; 178)
+        R_CURLY@[178; 179)
+    SEMI@[179; 180)
+  WHITESPACE@[180; 181)
diff --git a/crates/ra_syntax/tests/data/parser/inline/0116_use_star.rs b/crates/ra_syntax/tests/data/parser/inline/0116_use_star.rs
new file mode 100644
index 000000000..6f15769a8
--- /dev/null
+++ b/crates/ra_syntax/tests/data/parser/inline/0116_use_star.rs
@@ -0,0 +1,4 @@
+use *;
+use ::*;
+use some::path::{*};
+use some::path::{::*};
diff --git a/crates/ra_syntax/tests/data/parser/inline/0116_use_star.txt b/crates/ra_syntax/tests/data/parser/inline/0116_use_star.txt
new file mode 100644
index 000000000..2db3cbf9e
--- /dev/null
+++ b/crates/ra_syntax/tests/data/parser/inline/0116_use_star.txt
@@ -0,0 +1,59 @@
+SOURCE_FILE@[0; 60)
+  USE_ITEM@[0; 6)
+    USE_KW@[0; 3)
+    WHITESPACE@[3; 4)
+    USE_TREE@[4; 5)
+      STAR@[4; 5)
+    SEMI@[5; 6)
+  WHITESPACE@[6; 7)
+  USE_ITEM@[7; 15)
+    USE_KW@[7; 10)
+    WHITESPACE@[10; 11)
+    USE_TREE@[11; 14)
+      COLONCOLON@[11; 13)
+      STAR@[13; 14)
+    SEMI@[14; 15)
+  WHITESPACE@[15; 16)
+  USE_ITEM@[16; 36)
+    USE_KW@[16; 19)
+    WHITESPACE@[19; 20)
+    USE_TREE@[20; 35)
+      PATH@[20; 30)
+        PATH@[20; 24)
+          PATH_SEGMENT@[20; 24)
+            NAME_REF@[20; 24)
+              IDENT@[20; 24) "some"
+        COLONCOLON@[24; 26)
+        PATH_SEGMENT@[26; 30)
+          NAME_REF@[26; 30)
+            IDENT@[26; 30) "path"
+      COLONCOLON@[30; 32)
+      USE_TREE_LIST@[32; 35)
+        L_CURLY@[32; 33)
+        USE_TREE@[33; 34)
+          STAR@[33; 34)
+        R_CURLY@[34; 35)
+    SEMI@[35; 36)
+  WHITESPACE@[36; 37)
+  USE_ITEM@[37; 59)
+    USE_KW@[37; 40)
+    WHITESPACE@[40; 41)
+    USE_TREE@[41; 58)
+      PATH@[41; 51)
+        PATH@[41; 45)
+          PATH_SEGMENT@[41; 45)
+            NAME_REF@[41; 45)
+              IDENT@[41; 45) "some"
+        COLONCOLON@[45; 47)
+        PATH_SEGMENT@[47; 51)
+          NAME_REF@[47; 51)
+            IDENT@[47; 51) "path"
+      COLONCOLON@[51; 53)
+      USE_TREE_LIST@[53; 58)
+        L_CURLY@[53; 54)
+        USE_TREE@[54; 57)
+          COLONCOLON@[54; 56)
+          STAR@[56; 57)
+        R_CURLY@[57; 58)
+    SEMI@[58; 59)
+  WHITESPACE@[59; 60)
diff --git a/crates/ra_syntax/tests/data/parser/inline/0117_use_tree_list_after_path.rs b/crates/ra_syntax/tests/data/parser/inline/0117_use_tree_list_after_path.rs
new file mode 100644
index 000000000..c0a3d634e
--- /dev/null
+++ b/crates/ra_syntax/tests/data/parser/inline/0117_use_tree_list_after_path.rs
@@ -0,0 +1,2 @@
+use crate::{Item};
+use self::{Item};
diff --git a/crates/ra_syntax/tests/data/parser/inline/0117_use_tree_list_after_path.txt b/crates/ra_syntax/tests/data/parser/inline/0117_use_tree_list_after_path.txt
new file mode 100644
index 000000000..cac746e5b
--- /dev/null
+++ b/crates/ra_syntax/tests/data/parser/inline/0117_use_tree_list_after_path.txt
@@ -0,0 +1,37 @@
+SOURCE_FILE@[0; 37)
+  USE_ITEM@[0; 18)
+    USE_KW@[0; 3)
+    WHITESPACE@[3; 4)
+    USE_TREE@[4; 17)
+      PATH@[4; 9)
+        PATH_SEGMENT@[4; 9)
+          CRATE_KW@[4; 9)
+      COLONCOLON@[9; 11)
+      USE_TREE_LIST@[11; 17)
+        L_CURLY@[11; 12)
+        USE_TREE@[12; 16)
+          PATH@[12; 16)
+            PATH_SEGMENT@[12; 16)
+              NAME_REF@[12; 16)
+                IDENT@[12; 16) "Item"
+        R_CURLY@[16; 17)
+    SEMI@[17; 18)
+  WHITESPACE@[18; 19)
+  USE_ITEM@[19; 36)
+    USE_KW@[19; 22)
+    WHITESPACE@[22; 23)
+    USE_TREE@[23; 35)
+      PATH@[23; 27)
+        PATH_SEGMENT@[23; 27)
+          SELF_KW@[23; 27)
+      COLONCOLON@[27; 29)
+      USE_TREE_LIST@[29; 35)
+        L_CURLY@[29; 30)
+        USE_TREE@[30; 34)
+          PATH@[30; 34)
+            PATH_SEGMENT@[30; 34)
+              NAME_REF@[30; 34)
+                IDENT@[30; 34) "Item"
+        R_CURLY@[34; 35)
+    SEMI@[35; 36)
+  WHITESPACE@[36; 37)
diff --git a/crates/ra_syntax/tests/data/parser/inline/0118_use_tree_list.rs b/crates/ra_syntax/tests/data/parser/inline/0118_use_tree_list.rs
new file mode 100644
index 000000000..06c387cee
--- /dev/null
+++ b/crates/ra_syntax/tests/data/parser/inline/0118_use_tree_list.rs
@@ -0,0 +1,4 @@
+use {crate::path::from::root, or::path::from::crate_name}; // Rust 2018 (with a crate named `or`)
+use {path::from::root}; // Rust 2015
+use ::{some::arbritrary::path}; // Rust 2015
+use ::{{{crate::export}}}; // Nonsensical but perfectly legal nestnig
diff --git a/crates/ra_syntax/tests/data/parser/inline/0118_use_tree_list.txt b/crates/ra_syntax/tests/data/parser/inline/0118_use_tree_list.txt
new file mode 100644
index 000000000..89a0b9f2a
--- /dev/null
+++ b/crates/ra_syntax/tests/data/parser/inline/0118_use_tree_list.txt
@@ -0,0 +1,135 @@
+SOURCE_FILE@[0; 250)
+  USE_ITEM@[0; 58)
+    USE_KW@[0; 3)
+    WHITESPACE@[3; 4)
+    USE_TREE@[4; 57)
+      USE_TREE_LIST@[4; 57)
+        L_CURLY@[4; 5)
+        USE_TREE@[5; 28)
+          PATH@[5; 28)
+            PATH@[5; 22)
+              PATH@[5; 16)
+                PATH@[5; 10)
+                  PATH_SEGMENT@[5; 10)
+                    CRATE_KW@[5; 10)
+                COLONCOLON@[10; 12)
+                PATH_SEGMENT@[12; 16)
+                  NAME_REF@[12; 16)
+                    IDENT@[12; 16) "path"
+              COLONCOLON@[16; 18)
+              PATH_SEGMENT@[18; 22)
+                NAME_REF@[18; 22)
+                  IDENT@[18; 22) "from"
+            COLONCOLON@[22; 24)
+            PATH_SEGMENT@[24; 28)
+              NAME_REF@[24; 28)
+                IDENT@[24; 28) "root"
+        COMMA@[28; 29)
+        WHITESPACE@[29; 30)
+        USE_TREE@[30; 56)
+          PATH@[30; 56)
+            PATH@[30; 44)
+              PATH@[30; 38)
+                PATH@[30; 32)
+                  PATH_SEGMENT@[30; 32)
+                    NAME_REF@[30; 32)
+                      IDENT@[30; 32) "or"
+                COLONCOLON@[32; 34)
+                PATH_SEGMENT@[34; 38)
+                  NAME_REF@[34; 38)
+                    IDENT@[34; 38) "path"
+              COLONCOLON@[38; 40)
+              PATH_SEGMENT@[40; 44)
+                NAME_REF@[40; 44)
+                  IDENT@[40; 44) "from"
+            COLONCOLON@[44; 46)
+            PATH_SEGMENT@[46; 56)
+              NAME_REF@[46; 56)
+                IDENT@[46; 56) "crate_name"
+        R_CURLY@[56; 57)
+    SEMI@[57; 58)
+  WHITESPACE@[58; 59)
+  COMMENT@[59; 97)
+  WHITESPACE@[97; 98)
+  USE_ITEM@[98; 121)
+    USE_KW@[98; 101)
+    WHITESPACE@[101; 102)
+    USE_TREE@[102; 120)
+      USE_TREE_LIST@[102; 120)
+        L_CURLY@[102; 103)
+        USE_TREE@[103; 119)
+          PATH@[103; 119)
+            PATH@[103; 113)
+              PATH@[103; 107)
+                PATH_SEGMENT@[103; 107)
+                  NAME_REF@[103; 107)
+                    IDENT@[103; 107) "path"
+              COLONCOLON@[107; 109)
+              PATH_SEGMENT@[109; 113)
+                NAME_REF@[109; 113)
+                  IDENT@[109; 113) "from"
+            COLONCOLON@[113; 115)
+            PATH_SEGMENT@[115; 119)
+              NAME_REF@[115; 119)
+                IDENT@[115; 119) "root"
+        R_CURLY@[119; 120)
+    SEMI@[120; 121)
+  WHITESPACE@[121; 122)
+  COMMENT@[122; 134)
+  WHITESPACE@[134; 135)
+  USE_ITEM@[135; 166)
+    USE_KW@[135; 138)
+    WHITESPACE@[138; 139)
+    USE_TREE@[139; 165)
+      COLONCOLON@[139; 141)
+      USE_TREE_LIST@[141; 165)
+        L_CURLY@[141; 142)
+        USE_TREE@[142; 164)
+          PATH@[142; 164)
+            PATH@[142; 158)
+              PATH@[142; 146)
+                PATH_SEGMENT@[142; 146)
+                  NAME_REF@[142; 146)
+                    IDENT@[142; 146) "some"
+              COLONCOLON@[146; 148)
+              PATH_SEGMENT@[148; 158)
+                NAME_REF@[148; 158)
+                  IDENT@[148; 158) "arbritrary"
+            COLONCOLON@[158; 160)
+            PATH_SEGMENT@[160; 164)
+              NAME_REF@[160; 164)
+                IDENT@[160; 164) "path"
+        R_CURLY@[164; 165)
+    SEMI@[165; 166)
+  WHITESPACE@[166; 167)
+  COMMENT@[167; 179)
+  WHITESPACE@[179; 180)
+  USE_ITEM@[180; 206)
+    USE_KW@[180; 183)
+    WHITESPACE@[183; 184)
+    USE_TREE@[184; 205)
+      COLONCOLON@[184; 186)
+      USE_TREE_LIST@[186; 205)
+        L_CURLY@[186; 187)
+        USE_TREE@[187; 204)
+          USE_TREE_LIST@[187; 204)
+            L_CURLY@[187; 188)
+            USE_TREE@[188; 203)
+              USE_TREE_LIST@[188; 203)
+                L_CURLY@[188; 189)
+                USE_TREE@[189; 202)
+                  PATH@[189; 202)
+                    PATH@[189; 194)
+                      PATH_SEGMENT@[189; 194)
+                        CRATE_KW@[189; 194)
+                    COLONCOLON@[194; 196)
+                    PATH_SEGMENT@[196; 202)
+                      NAME_REF@[196; 202)
+                        IDENT@[196; 202) "export"
+                R_CURLY@[202; 203)
+            R_CURLY@[203; 204)
+        R_CURLY@[204; 205)
+    SEMI@[205; 206)
+  WHITESPACE@[206; 207)
+  COMMENT@[207; 249)
+  WHITESPACE@[249; 250)