Skip to content

Commit 6f9c454

Browse files
P1n3appl3P1n3appl3
committed
Respond to comments
1 parent 99d0fd9 commit 6f9c454

File tree

1 file changed

+26
-18
lines changed

1 file changed

+26
-18
lines changed

‎text/0000-rustdoc-json.md

Lines changed: 26 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -208,7 +208,7 @@ local crate, as well as some information about external items that are referred
208208

209209
Name | Type | Description
210210
----------|---------|------------------------------------------------------------------------------
211-
`name` | String | The name of the crate. If `--crate-name` is not given, based on the filename.
211+
`name` | String | (*Optional*) The name of the crate. If `--crate-name` is not given, based on the filename.
212212
`version` | String | (*Optional*) The version string given to `--crate-version`, if any.
213213
`includes_private` | bool | Whether or not the output includes private items.
214214
`root` | [ID](#ID) | The ID of the root module Item.
@@ -256,9 +256,10 @@ Name | Type | Description
256256
`name` | String | The name of the Item, if present. Some Items, like impl blocks, do not have names.
257257
`span` | [Span](#Span) | (*Optional*) The source location of this Item.
258258
`visibility` | String | `"default"`, `"public"`, `"crate"`, or `"restricted"` (`pub(path)`).
259-
`restricted_path` | String | (*Optional*) If `visitility == "restricted"`, this field contains the path that it's restricted to.
259+
`restricted_path` | String | (*Optional*) If `visibility == "restricted"`, this field contains the path that it's restricted to.
260260
`docs` | String | The extracted documentation text from the Item.
261-
`attrs` | [String] | The attributes (other than doc comments) on the Item, rendered as strings.
261+
`links` | [[ID](#ID)] | A list of items corresponding to any intra-doc links in `docs` in order of appearance.
262+
`attrs` | [String] | The attributes (other than doc comments) on the Item, rendered as strings (e.g. `["#[inline]", "#[test]"]`).
262263
`deprecation` | [Deprecation](#Deprecation) | (*Optional*) Information about the Item's deprecation, if present.
263264
`kind` | String | The kind of Item this is. Determines what fields are in `inner`.
264265
`inner` | Object | The type-specific fields describing this Item. Check the `kind` field to determine what's available.
@@ -285,10 +286,10 @@ Name | Type | Description
285286
`struct_type` | String | Either `"plain"` for braced structs, `"tuple"` for tuple structs, or `"unit"` for unit structs.
286287
`generics` | [Generics](#Generics) | Information about the struct's type parameters and `where` clauses.
287288
`fields_stripped` | bool | Whether any fields have been removed from the result, due to being private or hidden.
288-
`fields` | [[ID](#ID)] | The list of fields in the struct. All of the corresponding Items have `kind == "structfield"`.
289+
`fields` | [[ID](#ID)] | The list of fields in the struct. All of the corresponding Items have `kind == "struct_field"`.
289290
`impls` | [[ID](#ID)] | All impls (both trait and inherent) for this type. All of the corresponding Items have `kind = "impl"`
290291

291-
### `kind == "structfield"`
292+
### `kind == "struct_field"`
292293

293294
Name | Type | Description
294295
--------------|----------|-------------------------------------------------------------------------
@@ -305,19 +306,20 @@ Name | Type | Description
305306

306307
### `kind == "variant"`
307308

308-
`inner` can be one of the 3 following objects:
309-
- `"plain"` (e.g. `Enum::Variant`)
310-
- `{"tuple": [Type]}` (e.g. `Enum::Variant(u32, String)`)
311-
- `{"struct": Object}` (e.g. `Enum::Variant{foo: u32, bar: String}`) in which case the `Object`
312-
has a single key `"struct"` with a value that's the same object as `inner` when `kind == "struct"`.
309+
Has a `variant_kind` field with 3 possible values and an `variant_inner` field with more info if
310+
necessary:
311+
- `"plain"` (e.g. `Enum::Variant`) with no `variant_inner` value.
312+
- `"tuple"` (e.g. `Enum::Variant(u32, String)`) with `"variant_inner": [Type]`
313+
- `"struct"` (e.g. `Enum::Variant{foo: u32, bar: String}`) with `"variant_inner": [ID]` which is a
314+
list of this variant's "struct_field" items.
313315

314316
### `kind == "trait"`
315317

316318
Name | Type | Description
317319
--------------|----------|-------------------------------------------------------------------------
318320
`is_auto` | bool | Whether this trait is an autotrait like `Sync`.
319321
`is_unsafe` | bool | Whether this is an `unsafe trait` such as `GlobalAlloc`.
320-
`items` | [[ID](#ID)] | The list of method, constant, and typedef items contained in this trait definition.
322+
`items` | [[ID](#ID)] | The list of associated items contained in this trait definition.
321323
`generics` | [Generics](#Generics) | Information about the trait's type parameters and `where` clauses.
322324
`bounds` | [[GenericBound](#GenericBound)] | Trait bounds for this trait definition (e.g. `trait Foo: Bar<T> + Clone`).
323325

@@ -366,9 +368,9 @@ Name | Type | Description
366368
`is_unsafe` | bool | Whether this impl is for an unsafe trait.
367369
`generics` | [Generics](#Generics) | Information about the impl's type parameters and `where` clauses.
368370
`provided_trait_methods` | [String] | The list of names for all provided methods in this impl block. This is provided for ease of access if you don't need more information from the `items` field.
369-
`trait` | [Type](#Type) | The trait being implemented or `null` if the impl is "inherent".
371+
`trait` | [Type](#Type) | (*Optional*) The trait being implemented or `null` if the impl is "inherent".
370372
`for` | [Type](#Type) | The type that the impl block is for.
371-
`items` | [[ID](#ID)] | The list of method, constant, and typedef items contained in this impl block.
373+
`items` | [[ID](#ID)] | The list of associated items contained in this impl block.
372374
`negative` | bool | Whether this is a negative impl (e.g. `!Sized` or `!Send`).
373375
`synthetic` | bool | Whether this is an impl that's implied by the compiler (for autotraits).
374376
`blanket_impl` | String | (*Optional*) The name of the generic parameter used for the blanket impl, if this impl was produced by one. For example `impl<T, U> Into<U> for T` would result in `blanket_impl == "T"`.
@@ -378,7 +380,7 @@ Name | Type | Description
378380
Name | Type | Description
379381
--------------|----------|-------------------------------------------------------------------------
380382
`type` | [Type](#Type) | The type of this constant.
381-
`expr` | String | The stringified expression of this constant.
383+
`expr` | String | The [unstable](#Unstable) stringified expression of this constant.
382384
`value` | String | (*Optional*) The value of the evaluated expression for this constant, which is only computed for numeric types.
383385
`is_literal` | bool | Whether this constant is a bool, numeric, string, or char literal.
384386

@@ -387,7 +389,7 @@ Name | Type | Description
387389
Name | Type | Description
388390
--------------|----------|-------------------------------------------------------------------------
389391
`type` | [Type](#Type) | The type of this static.
390-
`expr` | String | The stringified expression that this static is assigned to.
392+
`expr` | String | The [unstable](#Unstable) stringified expression that this static is assigned to.
391393
`mutable` | bool | Whether this static is mutable.
392394

393395
### `kind == "typedef"`
@@ -459,7 +461,7 @@ Name | Type | Description
459461
-----------|----------|----------------------------------------------------------------------------
460462
`filename` | String | The path to the source file for this span relative to the crate root.
461463
`begin` | (int, int) | The zero indexed line and column of the first character in this span.
462-
`begin` | (int, int) | The zero indexed line and column of the last character in this span.
464+
`end` | (int, int) | The zero indexed line and column of the last character in this span.
463465

464466
## Deprecation
465467

@@ -472,7 +474,7 @@ Name | Type | Description
472474

473475
Name | Type | Description
474476
-----------|----------|----------------------------------------------------------------------------
475-
`inputs` | [(String, [Type](#Type))] | A list of parameter names and their types.
477+
`inputs` | [(String, [Type](#Type))] | A list of parameter names and their types. The names are [unstable](#Unstable) because arbitrary patterns can be used as parameters, in which case the name is a pretty printed version of it. For example `fn foo((_, x): (u32, u32)){…}` would have an parameter with the name `"(_, x)"` and `fn foo(MyStruct {some_field: u32, ..}: MyStruct){…}`) would have one called `"MyStruct {some_field, ..}"`.
476478
`output` | [Type](#Type) | (*Optional*) Output type.
477479
`c_variadic` | bool | Whether this function uses [an unstable feature](https://doc.rust-lang.org/beta/unstable-book/language-features/c-variadic.html) for variadic FFI functions.
478480

@@ -714,7 +716,7 @@ Name | Type | Description
714716
Name | Type | Description
715717
-----------|----------|----------------------------------------------------------------------------
716718
`type` | [Type](#Type) | The Type of the elements in the array
717-
`len` | String | The length of the array as a stringified expression.
719+
`len` | String | The length of the array as an [unstable](#Unstable) stringified expression.
718720

719721
### `kind = "impl_trait"`
720722

@@ -1016,6 +1018,12 @@ pub fn generic_args<'a>(x: impl MyTrait<'a, i32, Item = u8, Other = f32>) {
10161018
}
10171019
```
10181020

1021+
## Unstable
1022+
1023+
Fields marked as unstable have contents that are subject to change. They can be displayed to
1024+
users, but tools shouldn't rely on being able to parse their output or they will be broken by
1025+
internal compiler changes.
1026+
10191027
# Drawbacks
10201028
[drawbacks]: #drawbacks
10211029

0 commit comments

Comments
 (0)