eRFC: Add JSON backend to Rustdoc #2963
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -208,7 +208,7 @@ local crate, as well as some information about external items that are referred | |||||
|
|
||||||
| Name | Type | Description | ||||||
| ----------|---------|------------------------------------------------------------------------------ | ||||||
| `name` | String | (*Optional*) The name of the crate. If `--crate-name` is not given, based on the filename. | ||||||
| `version` | String | (*Optional*) The version string given to `--crate-version`, if any. | ||||||
| `includes_private` | bool | Whether or not the output includes private items. | ||||||
| `root` | [ID](#ID) | The ID of the root module Item. | ||||||
|
|
@@ -256,9 +256,10 @@ Name | Type | Description | |||||
| `name` | String | The name of the Item, if present. Some Items, like impl blocks, do not have names. | ||||||
P1n3appl3 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| `span` | [Span](#Span) | (*Optional*) The source location of this Item. | ||||||
|
There was a problem hiding this comment. Even though we don't output the source files themselves like the HTML backend, an alternative frontend could get the source and use these to link to it. |
||||||
| `visibility` | String | `"default"`, `"public"`, `"crate"`, or `"restricted"` (`pub(path)`). | ||||||
| `restricted_path` | String | (*Optional*) If `visibility == "restricted"`, this field contains the path that it's restricted to. | ||||||
| `docs` | String | The extracted documentation text from the Item. | ||||||
|
There was a problem hiding this comment. Will this include resolved intra-doc links? If not, is it possible to add them somehow? There was a problem hiding this comment. Yes, see the other comment about docs |
||||||
| `links` | [[ID](#ID)] | A list of items corresponding to any intra-doc links in `docs` in order of appearance. | ||||||
|
There was a problem hiding this comment. What happens if there are broken links? For the following code, I think rustdoc will internally store /// Link to [`MissingItem`], [`f`]
pub fn f() {}I think a map from the name to the id is more resilient. Alternatively we could store There was a problem hiding this comment. Yeah a mapping does sound better, i was worried at first that we couldn't use a map because of duplicate keys but that isn't an issue because there's no way to have the same name resolve to different stuff. There was a problem hiding this comment. Hmm now that you say that I'm not actually sure it's true ... consider: pub struct S;
/// Link to [S]
pub fn f() {}
pub mod inner {
pub struct S;
/// Link to [S]
pub fn g();
}Maybe we should include the ID of the item being documented as one of the keys? There was a problem hiding this comment. I think we're still fine, this mapping is just for a single item's docstring so in that context it could only refer to one of them. |
||||||
| `attrs` | [String] | The attributes (other than doc comments) on the Item, rendered as strings (e.g. `["#[inline]", "#[test]"]`). | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| `deprecation` | [Deprecation](#Deprecation) | (*Optional*) Information about the Item's deprecation, if present. | ||||||
| `kind` | String | The kind of Item this is. Determines what fields are in `inner`. | ||||||
| `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 | |||||
| `struct_type` | String | Either `"plain"` for braced structs, `"tuple"` for tuple structs, or `"unit"` for unit structs. | ||||||
| `generics` | [Generics](#Generics) | Information about the struct's type parameters and `where` clauses. | ||||||
| `fields_stripped` | bool | Whether any fields have been removed from the result, due to being private or hidden. | ||||||
| `fields` | [[ID](#ID)] | The list of fields in the struct. All of the corresponding Items have `kind == "struct_field"`. | ||||||
| `impls` | [[ID](#ID)] | All impls (both trait and inherent) for this type. All of the corresponding Items have `kind = "impl"` | ||||||
|
|
||||||
| ### `kind == "struct_field"` | ||||||
|
|
||||||
| Name | Type | Description | ||||||
| --------------|----------|------------------------------------------------------------------------- | ||||||
|
|
@@ -305,19 +306,20 @@ Name | Type | Description | |||||
|
|
||||||
| ### `kind == "variant"` | ||||||
|
|
||||||
| Has a `variant_kind` field with 3 possible values and an `variant_inner` field with more info if | ||||||
| necessary: | ||||||
| - `"plain"` (e.g. `Enum::Variant`) with no `variant_inner` value. | ||||||
| - `"tuple"` (e.g. `Enum::Variant(u32, String)`) with `"variant_inner": [Type]` | ||||||
| - `"struct"` (e.g. `Enum::Variant{foo: u32, bar: String}`) with `"variant_inner": [ID]` which is a | ||||||
| list of this variant's "struct_field" items. | ||||||
|
|
||||||
| ### `kind == "trait"` | ||||||
|
|
||||||
| Name | Type | Description | ||||||
| --------------|----------|------------------------------------------------------------------------- | ||||||
| `is_auto` | bool | Whether this trait is an autotrait like `Sync`. | ||||||
| `is_unsafe` | bool | Whether this is an `unsafe trait` such as `GlobalAlloc`. | ||||||
| `items` | [[ID](#ID)] | The list of associated items contained in this trait definition. | ||||||
| `generics` | [Generics](#Generics) | Information about the trait's type parameters and `where` clauses. | ||||||
| `bounds` | [[GenericBound](#GenericBound)] | Trait bounds for this trait definition (e.g. `trait Foo: Bar<T> + Clone`). | ||||||
|
|
||||||
|
|
@@ -366,9 +368,9 @@ Name | Type | Description | |||||
| `is_unsafe` | bool | Whether this impl is for an unsafe trait. | ||||||
| `generics` | [Generics](#Generics) | Information about the impl's type parameters and `where` clauses. | ||||||
| `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. | ||||||
| `trait` | [Type](#Type) | (*Optional*) The trait being implemented or `null` if the impl is "inherent". | ||||||
|
There was a problem hiding this comment. Should we explain what inherent means? pub struct S;
impl S { ... }There was a problem hiding this comment. yeah i definitely had to look that up when i read the code. |
||||||
| `for` | [Type](#Type) | The type that the impl block is for. | ||||||
| `items` | [[ID](#ID)] | The list of associated items contained in this impl block. | ||||||
| `negative` | bool | Whether this is a negative impl (e.g. `!Sized` or `!Send`). | ||||||
| `synthetic` | bool | Whether this is an impl that's implied by the compiler (for autotraits). | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| `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 | |||||
| Name | Type | Description | ||||||
| --------------|----------|------------------------------------------------------------------------- | ||||||
| `type` | [Type](#Type) | The type of this constant. | ||||||
| `expr` | String | The [unstable](#Unstable) stringified expression of this constant. | ||||||
| `value` | String | (*Optional*) The value of the evaluated expression for this constant, which is only computed for numeric types. | ||||||
| `is_literal` | bool | Whether this constant is a bool, numeric, string, or char literal. | ||||||
|
|
||||||
|
|
@@ -387,7 +389,7 @@ Name | Type | Description | |||||
| Name | Type | Description | ||||||
| --------------|----------|------------------------------------------------------------------------- | ||||||
| `type` | [Type](#Type) | The type of this static. | ||||||
| `expr` | String | The [unstable](#Unstable) stringified expression that this static is assigned to. | ||||||
| `mutable` | bool | Whether this static is mutable. | ||||||
|
|
||||||
| ### `kind == "typedef"` | ||||||
|
|
@@ -459,7 +461,7 @@ Name | Type | Description | |||||
| -----------|----------|---------------------------------------------------------------------------- | ||||||
| `filename` | String | The path to the source file for this span relative to the crate root. | ||||||
| `begin` | (int, int) | The zero indexed line and column of the first character in this span. | ||||||
| `end` | (int, int) | The zero indexed line and column of the last character in this span. | ||||||
|
|
||||||
| ## Deprecation | ||||||
|
|
||||||
|
|
@@ -472,7 +474,7 @@ Name | Type | Description | |||||
|
|
||||||
| Name | Type | Description | ||||||
| -----------|----------|---------------------------------------------------------------------------- | ||||||
| `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, ..}"`. | ||||||
| `output` | [Type](#Type) | (*Optional*) Output type. | ||||||
| `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. | ||||||
|
|
||||||
|
|
@@ -714,7 +716,7 @@ Name | Type | Description | |||||
| Name | Type | Description | ||||||
| -----------|----------|---------------------------------------------------------------------------- | ||||||
| `type` | [Type](#Type) | The Type of the elements in the array | ||||||
| `len` | String | The length of the array as an [unstable](#Unstable) stringified expression. | ||||||
|
|
||||||
| ### `kind = "impl_trait"` | ||||||
|
|
||||||
|
|
@@ -1016,6 +1018,12 @@ pub fn generic_args<'a>(x: impl MyTrait<'a, i32, Item = u8, Other = f32>) { | |||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| ## Unstable | ||||||
|
|
||||||
| Fields marked as unstable have contents that are subject to change. They can be displayed to | ||||||
| users, but tools shouldn't rely on being able to parse their output or they will be broken by | ||||||
| internal compiler changes. | ||||||
|
|
||||||
| # Drawbacks | ||||||
| [drawbacks]: #drawbacks | ||||||
|
|
||||||
|
|
||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was going to comment about being able to find that out from the items listed, but I realized you can't - if all the items are public, then this tells you that there were no private items, as opposed to hiding the private items.
No change necessary, just reasoning it out :)