better docs

Author: aDotInTheVoid

src/rustdoc-json-types/lib.rs

@@ -1038,8 +1038,17 @@ pub enum Type {
 pub struct Path {
     /// The path of the type.
     ///
-    /// This will be the path where the type is *used*, so it may be a
-    /// re-export.
+    /// This will be the path that is *used* (not where it is defined), so
+    /// multiple `Path`s may have different values for this field even if
+    /// they all refer to the same item. e.g.
+    ///
+    /// ```rust
+    /// pub type Vec1 = std::vec::Vec<i32>; // path: "std::vec::Vec"
+    /// pub type Vec2 = Vec<i32>; // path: "Vec"
+    /// pub type Vec3 = std::prelude::v1::Vec<i32>; // path: "std::prelude::v1::Vec"
+    /// ```
+    //
+    // Example tested in ./tests/rustdoc-json/path_name.rs
     pub path: String,
     /// The ID of the type.
     pub id: Id,

tests/rustdoc-json/path_name.rs

@@ -72,3 +72,12 @@ pub type Y4 = XPrivMod2;
 //@ has "$.paths[*].path" '["defines_and_reexports", "m2", "InPrivMod"]'
 //@ !has "$.paths[*].path" '["defines_and_reexports", "InPubMod"]'
 //@ !has "$.paths[*].path" '["defines_and_reexports", "InPrivMod"]'
+
+// Tests for the example in the docs of Path::name.
+// If these change, chage the docs.
+//@ is "$.index[*][?(@.name=='Vec1')].inner.type_alias.type.resolved_path.path" '"std::vec::Vec"'
+pub type Vec1 = std::vec::Vec<i32>;
+//@ is "$.index[*][?(@.name=='Vec2')].inner.type_alias.type.resolved_path.path" '"Vec"'
+pub type Vec2 = Vec<i32>;
+//@ is "$.index[*][?(@.name=='Vec3')].inner.type_alias.type.resolved_path.path" '"std::prelude::v1::Vec"'
+pub type Vec3 = std::prelude::v1::Vec<i32>;