Rustdoc-Json-Types: Better docs and names

aDotInTheVoid · aDotInTheVoid · commit cf6ed31044d6 · 2022-08-23T14:24:53.000+01:00
diff --git a/src/librustdoc/json/conversions.rs b/src/librustdoc/json/conversions.rs
@@ -243,7 +243,7 @@ fn from_clean_item(item: clean::Item, tcx: TyCtxt<'_>) -> ItemEnum {
         ImportItem(i) => ItemEnum::Import(i.into_tcx(tcx)),
         StructItem(s) => ItemEnum::Struct(s.into_tcx(tcx)),
         UnionItem(u) => ItemEnum::Union(u.into_tcx(tcx)),
-        StructFieldItem(f) => ItemEnum::StructField(f.into_tcx(tcx)),
+        StructFieldItem(f) => ItemEnum::Field(f.into_tcx(tcx)),
         EnumItem(e) => ItemEnum::Enum(e.into_tcx(tcx)),
         VariantItem(v) => ItemEnum::Variant(v.into_tcx(tcx)),
         FunctionItem(f) => ItemEnum::Function(from_function(f, header.unwrap(), tcx)),
@@ -325,7 +325,7 @@ impl FromWithTcx<clean::Union> for Union {
 
 pub(crate) fn from_ctor_kind(struct_type: CtorKind) -> StructKind {
     match struct_type {
-        CtorKind::Fictive => StructKind::Struct,
+        CtorKind::Fictive => StructKind::NamedFields,
         CtorKind::Fn => StructKind::Tuple,
         CtorKind::Const => StructKind::Unit,
     }
@@ -652,7 +652,7 @@ impl FromWithTcx<clean::Variant> for Variant {
                 fields_stripped: fields.iter().any(|i| i.is_stripped()),
             },
             Struct(s) => Variant {
-                kind: StructKind::Struct,
+                kind: StructKind::NamedFields,
                 fields: ids(&s.fields, tcx),
                 fields_stripped: s.has_stripped_entries(),
             },
diff --git a/src/librustdoc/json/mod.rs b/src/librustdoc/json/mod.rs
@@ -215,7 +215,7 @@ impl<'tcx> FormatRenderer<'tcx> for JsonRenderer<'tcx> {
                 | types::ItemEnum::PrimitiveType(_) => true,
                 types::ItemEnum::ExternCrate { .. }
                 | types::ItemEnum::Import(_)
-                | types::ItemEnum::StructField(_)
+                | types::ItemEnum::Field(_)
                 | types::ItemEnum::Variant(_)
                 | types::ItemEnum::Function(_)
                 | types::ItemEnum::TraitAlias(_)
diff --git a/src/rustdoc-json-types/lib.rs b/src/rustdoc-json-types/lib.rs
@@ -230,7 +230,8 @@ pub enum ItemEnum {
 
     Union(Union),
     Struct(Struct),
-    StructField(Type),
+    /// The name of the field is given in the enclosing [`Item`]
+    Field(Type),
     Enum(Enum),
     Variant(Variant),
 
@@ -283,6 +284,7 @@ pub struct Module {
 pub struct Union {
     pub generics: Generics,
     pub fields_stripped: bool,
+    /// Will all be [`ItemEnum::Field`]
     pub fields: Vec<Id>,
     pub impls: Vec<Id>,
 }
@@ -292,6 +294,7 @@ pub struct Struct {
     pub kind: StructKind,
     pub generics: Generics,
     pub fields_stripped: bool,
+    /// Will all be [`ItemEnum::Field`]
     pub fields: Vec<Id>,
     pub impls: Vec<Id>,
 }
@@ -300,22 +303,68 @@ pub struct Struct {
 pub struct Enum {
     pub generics: Generics,
     pub variants_stripped: bool,
+    /// Will all be [`ItemEnum::Variant`]
     pub variants: Vec<Id>,
     pub impls: Vec<Id>,
 }
 
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Variant {
     pub kind: StructKind,
+    /// Will all be [`ItemEnum::Field`]
     pub fields: Vec<Id>,
     pub fields_stripped: bool,
 }
 
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
+/// The kind used for literals of a struct or enum.
 pub enum StructKind {
-    Struct,
+    /// A "normal" struct, with named fields.
+    ///
+    /// Eg:
+    ///
+    /// ```rust
+    /// pub struct A {
+    ///     x: i32,
+    /// }
+    /// pub struct B {}
+    /// pub enum C {
+    ///     Variant { x: i32 },
+    /// }
+    /// pub enum D {
+    ///     Variant {},
+    /// }
+    /// ```
+    NamedFields,
+    /// Unnamed fields, accessed with a number.
+    ///
+    /// Eg:
+    ///
+    /// ```rust
+    /// pub struct A(i32);
+    /// pub struct B();
+    /// pub enum C {
+    ///     Variant(i32),
+    /// }
+    /// pub enum D {
+    ///     Variant(),
+    /// }
+    /// ```
     Tuple,
+    /// No fields, and no parentheses.
+    ///
+    /// Note: Cases without fields but with parentheses will have a different
+    /// kind, as seen in the examples above.
+    ///
+    /// Eg:
+    ///
+    /// ```rust
+    /// pub struct A;
+    /// pub enum B {
+    ///     Variant,
+    /// }
+    /// ```
     Unit,
 }
 
diff --git a/src/rustdoc-json-types/tests.rs b/src/rustdoc-json-types/tests.rs
@@ -3,7 +3,7 @@ use super::*;
 #[test]
 fn test_struct_info_roundtrip() {
     let s = ItemEnum::Struct(Struct {
-        kind: StructKind::Struct,
+        kind: StructKind::NamedFields,
         generics: Generics { params: vec![], where_predicates: vec![] },
         fields_stripped: false,
         fields: vec![],
diff --git a/src/test/rustdoc-json/enums/variant_struct.rs b/src/test/rustdoc-json/enums/variant_struct.rs
@@ -1,11 +1,8 @@
-// @has "$.index[*][?(@.name=='EnumStruct')].visibility" \"public\"
-// @has "$.index[*][?(@.name=='EnumStruct')].kind" \"enum\"
+// @is "$.index[*][?(@.name=='EnumStruct')].visibility" \"public\"
+// @is "$.index[*][?(@.name=='EnumStruct')].kind" \"enum\"
 pub enum EnumStruct {
-    // @has "$.index[*][?(@.name=='VariantS')].inner.kind" \"struct\"
-    // @has "$.index[*][?(@.name=='x')].kind" \"struct_field\"
-    // @has "$.index[*][?(@.name=='y')].kind" \"struct_field\"
-    VariantS {
-        x: u32,
-        y: String,
-    },
+    // @is "$.index[*][?(@.name=='VariantS')].inner.kind" \"named_fields\"
+    // @is "$.index[*][?(@.name=='x')].kind" \"field\"
+    // @is "$.index[*][?(@.name=='y')].kind" \"field\"
+    VariantS { x: u32, y: String },
 }
diff --git a/src/test/rustdoc-json/enums/variant_tuple_struct.rs b/src/test/rustdoc-json/enums/variant_tuple_struct.rs
@@ -1,8 +1,8 @@
-// @has "$.index[*][?(@.name=='EnumTupleStruct')].visibility" \"public\"
-// @has "$.index[*][?(@.name=='EnumTupleStruct')].kind" \"enum\"
+// @is "$.index[*][?(@.name=='EnumTupleStruct')].visibility" \"public\"
+// @is "$.index[*][?(@.name=='EnumTupleStruct')].kind" \"enum\"
 pub enum EnumTupleStruct {
-    // @has "$.index[*][?(@.name=='VariantA')].inner.kind" \"tuple\"
-    // @has "$.index[*][?(@.name=='0')].kind" \"struct_field\"
-    // @has "$.index[*][?(@.name=='1')].kind" \"struct_field\"
+    // @is "$.index[*][?(@.name=='VariantA')].inner.kind" \"tuple\"
+    // @is "$.index[*][?(@.name=='0')].kind" \"field\"
+    // @is "$.index[*][?(@.name=='1')].kind" \"field\"
     VariantA(u32, String),
 }
diff --git a/src/test/rustdoc-json/structs/plain_empty.rs b/src/test/rustdoc-json/structs/plain_empty.rs
@@ -1,6 +1,6 @@
 // @has "$.index[*][?(@.name=='PlainEmpty')].visibility" \"public\"
 // @has "$.index[*][?(@.name=='PlainEmpty')].kind" \"struct\"
-// @has "$.index[*][?(@.name=='PlainEmpty')].inner.kind" \"struct\"
+// @has "$.index[*][?(@.name=='PlainEmpty')].inner.kind" \"named_fields\"
 // @has "$.index[*][?(@.name=='PlainEmpty')].inner.fields_stripped" false
 // @has "$.index[*][?(@.name=='PlainEmpty')].inner.fields" []
 pub struct PlainEmpty {}
diff --git a/src/test/rustdoc-json/structs/with_generics.rs b/src/test/rustdoc-json/structs/with_generics.rs
@@ -6,7 +6,7 @@ use std::collections::HashMap;
 // @has "$.index[*][?(@.name=='WithGenerics')].inner.generics.params[0].kind.type"
 // @has "$.index[*][?(@.name=='WithGenerics')].inner.generics.params[1].name" \"U\"
 // @has "$.index[*][?(@.name=='WithGenerics')].inner.generics.params[1].kind.type"
-// @has "$.index[*][?(@.name=='WithGenerics')].inner.kind" \"struct\"
+// @has "$.index[*][?(@.name=='WithGenerics')].inner.kind" \"named_fields\"
 // @has "$.index[*][?(@.name=='WithGenerics')].inner.fields_stripped" true
 pub struct WithGenerics<T, U> {
     stuff: Vec<T>,
diff --git a/src/test/rustdoc-json/structs/with_primitives.rs b/src/test/rustdoc-json/structs/with_primitives.rs
@@ -2,7 +2,7 @@
 // @has "$.index[*][?(@.name=='WithPrimitives')].kind" \"struct\"
 // @has "$.index[*][?(@.name=='WithPrimitives')].inner.generics.params[0].name" \"\'a\"
 // @has "$.index[*][?(@.name=='WithPrimitives')].inner.generics.params[0].kind.lifetime.outlives" []
-// @has "$.index[*][?(@.name=='WithPrimitives')].inner.kind" \"struct\"
+// @has "$.index[*][?(@.name=='WithPrimitives')].inner.kind" \"named_fields\"
 // @has "$.index[*][?(@.name=='WithPrimitives')].inner.fields_stripped" true
 pub struct WithPrimitives<'a> {
     num: u32,
