Fully document `rustdoc-json-types` #127290

its-the-shrimp · 2024-07-03T20:49:34Z

100% of rustdoc-json-types is now documented
Here's the summary from rustdoc with -Zunstable-options --show-coverage:

+-------------------------------------+------------+------------+------------+------------+
| File                                | Documented | Percentage |   Examples | Percentage |
+-------------------------------------+------------+------------+------------+------------+
| src/rustdoc-json-types/lib.rs       |        314 |     100.0% |         23 |      31.9% |
+-------------------------------------+------------+------------+------------+------------+
| Total                               |        314 |     100.0% |         23 |      31.9% |
+-------------------------------------+------------+------------+------------+------------+

rustbot · 2024-07-03T20:49:42Z

r? @fmease

rustbot has assigned @fmease.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

rustbot · 2024-07-03T20:49:44Z

rustdoc-json-types is a public (although nightly-only) API. If possible, consider changing src/librustdoc/json/conversions.rs; otherwise, make sure you bump the FORMAT_VERSION constant.

cc @CraftSpider, @aDotInTheVoid, @Enselic, @obi1kenobi

its-the-shrimp · 2024-07-03T20:50:25Z

r? @aDotInTheVoid

bors · 2024-07-04T11:30:41Z

☔ The latest upstream changes (presumably #127305) made this pull request unmergeable. Please resolve the merge conflicts.

aDootInTheVoid

Thanks for working on this. Unfortunately, it needs a lot of changes before it's suitable to merge.

I've left a comment for all the major categories of issue, but not for each instance as that got unwieldy. When they've all been fixed, please mark this as ready, and I'll take another look at it.

@rustbot author

src/rustdoc-json-types/lib.rs

rustbot · 2024-07-06T18:51:03Z

There are merge commits (commits with multiple parents) in your changes. We have a no merge policy so these commits will need to be removed for this pull request to be merged.

You can start a rebase with the following commands:

$ # rebase
$ git pull --rebase https://github.com/rust-lang/rust.git master
$ git push --force-with-lease

The following commits are merge commits:

4624360

rustbot · 2024-07-06T19:56:53Z

There are merge commits (commits with multiple parents) in your changes. We have a no merge policy so these commits will need to be removed for this pull request to be merged.

You can start a rebase with the following commands:

$ # rebase
$ git pull --rebase https://github.com/rust-lang/rust.git master
$ git push --force-with-lease

The following commits are merge commits (since this message was last posted):

83d3158

its-the-shrimp · 2024-07-06T21:00:18Z

@rustbot review

I'm not sure about my wording for FORMAT_VERSION though, but I am sure that we should elaborate a bit on what does it actually convey, are there ways to improve?

bors · 2024-07-13T01:57:20Z

☔ The latest upstream changes (presumably #127665) made this pull request unmergeable. Please resolve the merge conflicts.

aDootInTheVoid

This is alot closer, thanks for working on it.

src/rustdoc-json-types/lib.rs

aDootInTheVoid · 2024-07-22T21:46:12Z

src/rustdoc-json-types/lib.rs

    pub synthetic: bool,
+    /// The name of the generic parameter used for the blanket impl, if this impl was produced by
+    /// one. For example, for `impl<T, U> Into<U> for T` this field would be `"T"`.


How is this different from for_?

As discussed here, I'm happy to leave this to a follup-up, as long as a FIXME comment is added to improve the situation here.

src/rustdoc-json-types/lib.rs

aDootInTheVoid · 2024-07-22T21:52:43Z

@rustbot author

its-the-shrimp · 2024-07-28T08:55:49Z

@rustbot review

aDootInTheVoid

@rustbot author

aDootInTheVoid · 2024-07-28T21:53:27Z

src/rustdoc-json-types/lib.rs

    pub synthetic: bool,
+    /// The name of the generic parameter used for the blanket impl, if this impl was produced by
+    /// one. For example, for `impl<T, U> Into<U> for T` this field would be `"T"`.


As discussed here, I'm happy to leave this to a follup-up, as long as a FIXME comment is added to improve the situation here.

aDootInTheVoid · 2024-07-28T22:00:45Z

src/rustdoc-json-types/lib.rs

 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum Type {
-    /// Structs, enums, and unions
+    /// Structs, enums, unions, etc., e.g. `std::option::Option<u32>`


It's better to exaustive here. This code:

rust/src/tools/jsondoclint/src/item_kind.rs

Lines 133 to 135 in 2cbbe8b

pub fn is_type(self) -> bool {

matches!(self, Kind::Struct | Kind::Enum | Kind::Union | Kind::TypeAlias)

}

controls the things we expect to find here. If you remove Kind::TypeAlias you can see where it appears here

aDootInTheVoid · 2024-07-28T22:02:19Z

src/rustdoc-json-types/lib.rs

    Generic(String),
-    /// Built in numeric (i*, u*, f*) types, bool, and char
+    /// Built-in types, such as the integers, floating-point numbers, `bool`, and `char`.


The problems is you suggest that all built-in types are documented as Type::Primitive, when this isn't the case. I.E. there are built-in types that arn't primitives (e.g. (i32, i32) and &'static str

its-the-shrimp · 2024-07-28T22:51:13Z

@rustbot review

aDotInTheVoid · 2024-07-28T23:30:21Z

This looks good to merge now. If you're able, you should squash the commits, as they arn't logically separate, and it makes tracking the format evolution easier.

r=me with commits squashed.

Thanks again for working on this, and sticking through the many rounds of review.

aDotInTheVoid · 2024-07-29T01:33:47Z

@bors r+ rollup

bors · 2024-07-29T01:33:49Z

📌 Commit c881f72 has been approved by aDotInTheVoid

It is now in the queue for this repository.

obi1kenobi · 2024-07-29T01:36:26Z

Nicely done, this is a major improvement and I love it!

…iaskrgr Rollup of 5 pull requests Successful merges: - rust-lang#109174 (Replace `io::Cursor::{remaining_slice, is_empty}`) - rust-lang#127290 (Fully document `rustdoc-json-types`) - rust-lang#128055 (std: unsafe-wrap personality::dwarf::eh) - rust-lang#128269 (improve cargo invocations on bootstrap) - rust-lang#128310 (Add missing periods on `BTreeMap` cursor `peek_next` docs) Failed merges: - rust-lang#127543 (More unsafe attr verification) - rust-lang#128182 (handle no_std targets on std builds) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of rust-lang#127290 - its-the-shrimp:document_rustdoc_json_types, r=aDotInTheVoid Fully document `rustdoc-json-types` 100% of `rustdoc-json-types` is now documented Here's the summary from rustdoc with `-Zunstable-options --show-coverage`: ``` +-------------------------------------+------------+------------+------------+------------+ | File | Documented | Percentage | Examples | Percentage | +-------------------------------------+------------+------------+------------+------------+ | src/rustdoc-json-types/lib.rs | 314 | 100.0% | 23 | 31.9% | +-------------------------------------+------------+------------+------------+------------+ | Total | 314 | 100.0% | 23 | 31.9% | +-------------------------------------+------------+------------+------------+------------+ ```

rustbot assigned fmease Jul 3, 2024

rustbot added A-rustdoc-json Area: Rustdoc JSON backend S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Jul 3, 2024

rustbot assigned aDotInTheVoid and unassigned fmease Jul 3, 2024

This comment has been minimized.

Sign in to view

its-the-shrimp force-pushed the document_rustdoc_json_types branch from d68cac0 to 662f4e5 Compare July 3, 2024 21:35

aDootInTheVoid suggested changes Jul 6, 2024

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 6, 2024

rustbot added the has-merge-commits PR has merge commits, merge with caution. label Jul 6, 2024

its-the-shrimp force-pushed the document_rustdoc_json_types branch from 4624360 to 83d3158 Compare July 6, 2024 19:56

its-the-shrimp force-pushed the document_rustdoc_json_types branch from 83d3158 to 15fef33 Compare July 6, 2024 20:23

rustbot removed the has-merge-commits PR has merge commits, merge with caution. label Jul 6, 2024

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jul 6, 2024

its-the-shrimp force-pushed the document_rustdoc_json_types branch from 29371be to 4980bf3 Compare July 20, 2024 12:54

aDootInTheVoid suggested changes Jul 22, 2024

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 22, 2024

its-the-shrimp force-pushed the document_rustdoc_json_types branch from 28b790b to 5ac2f69 Compare July 27, 2024 23:07

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jul 28, 2024

aDootInTheVoid suggested changes Jul 28, 2024

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 28, 2024

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jul 28, 2024

fully document rustdoc-json-types

c881f72

its-the-shrimp force-pushed the document_rustdoc_json_types branch from 537295d to c881f72 Compare July 28, 2024 23:56

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 29, 2024

matthiaskrgr mentioned this pull request Jul 29, 2024

Rollup of 5 pull requests #128330

Merged

bors merged commit 47b76d8 into rust-lang:master Jul 29, 2024
6 checks passed

rustbot added this to the 1.82.0 milestone Jul 29, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fully document `rustdoc-json-types` #127290

Fully document `rustdoc-json-types` #127290

its-the-shrimp commented Jul 3, 2024

rustbot commented Jul 3, 2024

rustbot commented Jul 3, 2024

its-the-shrimp commented Jul 3, 2024

This comment has been minimized.

bors commented Jul 4, 2024

aDootInTheVoid left a comment

rustbot commented Jul 6, 2024

rustbot commented Jul 6, 2024

its-the-shrimp commented Jul 6, 2024

bors commented Jul 13, 2024

aDootInTheVoid left a comment

aDootInTheVoid Jul 22, 2024

aDootInTheVoid Jul 28, 2024

aDootInTheVoid commented Jul 22, 2024

its-the-shrimp commented Jul 28, 2024

aDootInTheVoid left a comment

aDootInTheVoid Jul 28, 2024

aDootInTheVoid Jul 28, 2024

aDootInTheVoid Jul 28, 2024

its-the-shrimp commented Jul 28, 2024

aDotInTheVoid commented Jul 28, 2024

aDotInTheVoid commented Jul 29, 2024

bors commented Jul 29, 2024

obi1kenobi commented Jul 29, 2024

	pub fn is_type(self) -> bool {
	matches!(self, Kind::Struct \| Kind::Enum \| Kind::Union \| Kind::TypeAlias)
	}

Fully document rustdoc-json-types #127290

Fully document rustdoc-json-types #127290

Conversation

its-the-shrimp commented Jul 3, 2024

rustbot commented Jul 3, 2024

rustbot commented Jul 3, 2024

its-the-shrimp commented Jul 3, 2024

This comment has been minimized.

bors commented Jul 4, 2024

aDootInTheVoid left a comment

Choose a reason for hiding this comment

rustbot commented Jul 6, 2024

rustbot commented Jul 6, 2024

its-the-shrimp commented Jul 6, 2024

bors commented Jul 13, 2024

aDootInTheVoid left a comment

Choose a reason for hiding this comment

aDootInTheVoid Jul 22, 2024

Choose a reason for hiding this comment

aDootInTheVoid Jul 28, 2024

Choose a reason for hiding this comment

aDootInTheVoid commented Jul 22, 2024

its-the-shrimp commented Jul 28, 2024

aDootInTheVoid left a comment

Choose a reason for hiding this comment

aDootInTheVoid Jul 28, 2024

Choose a reason for hiding this comment

aDootInTheVoid Jul 28, 2024

Choose a reason for hiding this comment

aDootInTheVoid Jul 28, 2024

Choose a reason for hiding this comment

its-the-shrimp commented Jul 28, 2024

aDotInTheVoid commented Jul 28, 2024

aDotInTheVoid commented Jul 29, 2024

bors commented Jul 29, 2024

obi1kenobi commented Jul 29, 2024

Fully document `rustdoc-json-types` #127290

Fully document `rustdoc-json-types` #127290