Skip to content

Commit cf6ed31

Browse files
aDotInTheVoidaDotInTheVoid
committed
Rustdoc-Json-Types: Better docs and names
1 parent 9aa68e0 commit cf6ed31

File tree

9 files changed

+70
-24
lines changed

9 files changed

+70
-24
lines changed

‎src/librustdoc/json/conversions.rs

+3-3
Original file line numberDiff line numberDiff line change
@@ -243,7 +243,7 @@ fn from_clean_item(item: clean::Item, tcx: TyCtxt<'_>) -> ItemEnum {
243243
ImportItem(i) => ItemEnum::Import(i.into_tcx(tcx)),
244244
StructItem(s) => ItemEnum::Struct(s.into_tcx(tcx)),
245245
UnionItem(u) => ItemEnum::Union(u.into_tcx(tcx)),
246-
StructFieldItem(f) => ItemEnum::StructField(f.into_tcx(tcx)),
246+
StructFieldItem(f) => ItemEnum::Field(f.into_tcx(tcx)),
247247
EnumItem(e) => ItemEnum::Enum(e.into_tcx(tcx)),
248248
VariantItem(v) => ItemEnum::Variant(v.into_tcx(tcx)),
249249
FunctionItem(f) => ItemEnum::Function(from_function(f, header.unwrap(), tcx)),
@@ -325,7 +325,7 @@ impl FromWithTcx<clean::Union> for Union {
325325

326326
pub(crate) fn from_ctor_kind(struct_type: CtorKind) -> StructKind {
327327
match struct_type {
328-
CtorKind::Fictive => StructKind::Struct,
328+
CtorKind::Fictive => StructKind::NamedFields,
329329
CtorKind::Fn => StructKind::Tuple,
330330
CtorKind::Const => StructKind::Unit,
331331
}
@@ -652,7 +652,7 @@ impl FromWithTcx<clean::Variant> for Variant {
652652
fields_stripped: fields.iter().any(|i| i.is_stripped()),
653653
},
654654
Struct(s) => Variant {
655-
kind: StructKind::Struct,
655+
kind: StructKind::NamedFields,
656656
fields: ids(&s.fields, tcx),
657657
fields_stripped: s.has_stripped_entries(),
658658
},

‎src/librustdoc/json/mod.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,7 @@ impl<'tcx> FormatRenderer<'tcx> for JsonRenderer<'tcx> {
215215
| types::ItemEnum::PrimitiveType(_) => true,
216216
types::ItemEnum::ExternCrate { .. }
217217
| types::ItemEnum::Import(_)
218-
| types::ItemEnum::StructField(_)
218+
| types::ItemEnum::Field(_)
219219
| types::ItemEnum::Variant(_)
220220
| types::ItemEnum::Function(_)
221221
| types::ItemEnum::TraitAlias(_)

‎src/rustdoc-json-types/lib.rs

+51-2
Original file line numberDiff line numberDiff line change
@@ -230,7 +230,8 @@ pub enum ItemEnum {
230230

231231
Union(Union),
232232
Struct(Struct),
233-
StructField(Type),
233+
/// The name of the field is given in the enclosing [`Item`]
234+
Field(Type),
234235
Enum(Enum),
235236
Variant(Variant),
236237

@@ -283,6 +284,7 @@ pub struct Module {
283284
pub struct Union {
284285
pub generics: Generics,
285286
pub fields_stripped: bool,
287+
/// Will all be [`ItemEnum::Field`]
286288
pub fields: Vec<Id>,
287289
pub impls: Vec<Id>,
288290
}
@@ -292,6 +294,7 @@ pub struct Struct {
292294
pub kind: StructKind,
293295
pub generics: Generics,
294296
pub fields_stripped: bool,
297+
/// Will all be [`ItemEnum::Field`]
295298
pub fields: Vec<Id>,
296299
pub impls: Vec<Id>,
297300
}
@@ -300,22 +303,68 @@ pub struct Struct {
300303
pub struct Enum {
301304
pub generics: Generics,
302305
pub variants_stripped: bool,
306+
/// Will all be [`ItemEnum::Variant`]
303307
pub variants: Vec<Id>,
304308
pub impls: Vec<Id>,
305309
}
306310

307311
#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
308312
pub struct Variant {
309313
pub kind: StructKind,
314+
/// Will all be [`ItemEnum::Field`]
310315
pub fields: Vec<Id>,
311316
pub fields_stripped: bool,
312317
}
313318

314319
#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
315320
#[serde(rename_all = "snake_case")]
321+
/// The kind used for literals of a struct or enum.
316322
pub enum StructKind {
317-
Struct,
323+
/// A "normal" struct, with named fields.
324+
///
325+
/// Eg:
326+
///
327+
/// ```rust
328+
/// pub struct A {
329+
/// x: i32,
330+
/// }
331+
/// pub struct B {}
332+
/// pub enum C {
333+
/// Variant { x: i32 },
334+
/// }
335+
/// pub enum D {
336+
/// Variant {},
337+
/// }
338+
/// ```
339+
NamedFields,
340+
/// Unnamed fields, accessed with a number.
341+
///
342+
/// Eg:
343+
///
344+
/// ```rust
345+
/// pub struct A(i32);
346+
/// pub struct B();
347+
/// pub enum C {
348+
/// Variant(i32),
349+
/// }
350+
/// pub enum D {
351+
/// Variant(),
352+
/// }
353+
/// ```
318354
Tuple,
355+
/// No fields, and no parentheses.
356+
///
357+
/// Note: Cases without fields but with parentheses will have a different
358+
/// kind, as seen in the examples above.
359+
///
360+
/// Eg:
361+
///
362+
/// ```rust
363+
/// pub struct A;
364+
/// pub enum B {
365+
/// Variant,
366+
/// }
367+
/// ```
319368
Unit,
320369
}
321370

‎src/rustdoc-json-types/tests.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ use super::*;
33
#[test]
44
fn test_struct_info_roundtrip() {
55
let s = ItemEnum::Struct(Struct {
6-
kind: StructKind::Struct,
6+
kind: StructKind::NamedFields,
77
generics: Generics { params: vec![], where_predicates: vec![] },
88
fields_stripped: false,
99
fields: vec![],

‎src/test/rustdoc-json/enums/variant_struct.rs

+6-9
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,8 @@
1-
// @has "$.index[*][?(@.name=='EnumStruct')].visibility" \"public\"
2-
// @has "$.index[*][?(@.name=='EnumStruct')].kind" \"enum\"
1+
// @is "$.index[*][?(@.name=='EnumStruct')].visibility" \"public\"
2+
// @is "$.index[*][?(@.name=='EnumStruct')].kind" \"enum\"
33
pub enum EnumStruct {
4-
// @has "$.index[*][?(@.name=='VariantS')].inner.kind" \"struct\"
5-
// @has "$.index[*][?(@.name=='x')].kind" \"struct_field\"
6-
// @has "$.index[*][?(@.name=='y')].kind" \"struct_field\"
7-
VariantS {
8-
x: u32,
9-
y: String,
10-
},
4+
// @is "$.index[*][?(@.name=='VariantS')].inner.kind" \"named_fields\"
5+
// @is "$.index[*][?(@.name=='x')].kind" \"field\"
6+
// @is "$.index[*][?(@.name=='y')].kind" \"field\"
7+
VariantS { x: u32, y: String },
118
}

‎src/test/rustdoc-json/enums/variant_tuple_struct.rs

+5-5
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
// @has "$.index[*][?(@.name=='EnumTupleStruct')].visibility" \"public\"
2-
// @has "$.index[*][?(@.name=='EnumTupleStruct')].kind" \"enum\"
1+
// @is "$.index[*][?(@.name=='EnumTupleStruct')].visibility" \"public\"
2+
// @is "$.index[*][?(@.name=='EnumTupleStruct')].kind" \"enum\"
33
pub enum EnumTupleStruct {
4-
// @has "$.index[*][?(@.name=='VariantA')].inner.kind" \"tuple\"
5-
// @has "$.index[*][?(@.name=='0')].kind" \"struct_field\"
6-
// @has "$.index[*][?(@.name=='1')].kind" \"struct_field\"
4+
// @is "$.index[*][?(@.name=='VariantA')].inner.kind" \"tuple\"
5+
// @is "$.index[*][?(@.name=='0')].kind" \"field\"
6+
// @is "$.index[*][?(@.name=='1')].kind" \"field\"
77
VariantA(u32, String),
88
}

‎src/test/rustdoc-json/structs/plain_empty.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// @has "$.index[*][?(@.name=='PlainEmpty')].visibility" \"public\"
22
// @has "$.index[*][?(@.name=='PlainEmpty')].kind" \"struct\"
3-
// @has "$.index[*][?(@.name=='PlainEmpty')].inner.kind" \"struct\"
3+
// @has "$.index[*][?(@.name=='PlainEmpty')].inner.kind" \"named_fields\"
44
// @has "$.index[*][?(@.name=='PlainEmpty')].inner.fields_stripped" false
55
// @has "$.index[*][?(@.name=='PlainEmpty')].inner.fields" []
66
pub struct PlainEmpty {}

‎src/test/rustdoc-json/structs/with_generics.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ use std::collections::HashMap;
66
// @has "$.index[*][?(@.name=='WithGenerics')].inner.generics.params[0].kind.type"
77
// @has "$.index[*][?(@.name=='WithGenerics')].inner.generics.params[1].name" \"U\"
88
// @has "$.index[*][?(@.name=='WithGenerics')].inner.generics.params[1].kind.type"
9-
// @has "$.index[*][?(@.name=='WithGenerics')].inner.kind" \"struct\"
9+
// @has "$.index[*][?(@.name=='WithGenerics')].inner.kind" \"named_fields\"
1010
// @has "$.index[*][?(@.name=='WithGenerics')].inner.fields_stripped" true
1111
pub struct WithGenerics<T, U> {
1212
stuff: Vec<T>,

‎src/test/rustdoc-json/structs/with_primitives.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
// @has "$.index[*][?(@.name=='WithPrimitives')].kind" \"struct\"
33
// @has "$.index[*][?(@.name=='WithPrimitives')].inner.generics.params[0].name" \"\'a\"
44
// @has "$.index[*][?(@.name=='WithPrimitives')].inner.generics.params[0].kind.lifetime.outlives" []
5-
// @has "$.index[*][?(@.name=='WithPrimitives')].inner.kind" \"struct\"
5+
// @has "$.index[*][?(@.name=='WithPrimitives')].inner.kind" \"named_fields\"
66
// @has "$.index[*][?(@.name=='WithPrimitives')].inner.fields_stripped" true
77
pub struct WithPrimitives<'a> {
88
num: u32,

0 commit comments

Comments
 (0)