Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

implement struct_now_doc_hidden lint #587

Merged
merged 15 commits into from
Nov 28, 2023
Merged

implement struct_now_doc_hidden lint #587

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
4810db7
implement struct_now_doc_hidden lint
u9g Nov 25, 2023
56a3791
Update src/lints/struct_now_doc_hidden.ron
u9g Nov 25, 2023
a8d279c
no need to filter on struct type
u9g Nov 28, 2023
35897c8
Update src/lints/struct_now_doc_hidden.ron
u9g Nov 28, 2023
b3c3e45
Update src/lints/struct_now_doc_hidden.ron
u9g Nov 28, 2023
ded09b0
fix no end new line
u9g Nov 28, 2023
17ca637
remove struct_type from expected output
u9g Nov 28, 2023
88ced54
add struct-in-mod tests
u9g Nov 28, 2023
38115fd
add even more nested mods
u9g Nov 28, 2023
21f829d
add mispelled doc hidden and hidden field to tests
u9g Nov 28, 2023
bc0de14
add better explanation comment
u9g Nov 28, 2023
f605781
add test for adding doc hidden to a now-private struct
u9g Nov 28, 2023
ed0424e
add comment to test
u9g Nov 28, 2023
a333bae
add test for possible doc hidden mistake
u9g Nov 28, 2023
22798c0
replace invalid test with valid test of alias of hidden
u9g Nov 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions src/lints/struct_now_doc_hidden.ron
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
SemverQuery(
id: "struct_now_doc_hidden",
human_readable_name: "pub struct is now #[doc(hidden)]",
description: "A pub struct is now hidden from documentation effectively removing it from the crate's public api.",
u9g marked this conversation as resolved.
Show resolved Hide resolved
required_update: Major,
reference_link: Some("https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html#hidden"),
query: r#"
{
CrateDiff {
baseline {
item {
... on Struct {
visibility_limit @filter(op: "=", value: ["$public"])
struct_type @output @tag

importable_path {
path @output @tag
public_api @filter(op: "=", value: ["$true"])
}
}
}
}
current {
item {
... on Struct {
visibility_limit @filter(op: "=", value: ["$public"])
struct_name: name @output
struct_type @filter(op: "=", value: ["%struct_type"])
u9g marked this conversation as resolved.
Show resolved Hide resolved

importable_path {
path @filter(op: "=", value: ["%path"])
public_api @filter(op: "!=", value: ["$true"])
}

span_: span @optional {
filename @output
begin_line @output
}
}
}
}
}
}"#,
arguments: {
"public": "public",
"true": true,
},
error_message: "A publicly visible struct is now hidden via #[doc(hidden)].",
u9g marked this conversation as resolved.
Show resolved Hide resolved
per_result_error_template: Some("Struct {{struct_name}} in file {{span_filename}}:{{span_begin_line}}"),
u9g marked this conversation as resolved.
Show resolved Hide resolved
)
1 change: 1 addition & 0 deletions src/query.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -495,6 +495,7 @@ add_lints!(
struct_marked_non_exhaustive,
struct_missing,
struct_must_use_added,
struct_now_doc_hidden,
struct_pub_field_missing,
struct_repr_c_removed,
struct_repr_transparent_removed,
Expand Down
7 changes: 7 additions & 0 deletions test_crates/struct_now_doc_hidden/new/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
[package]
publish = false
name = "struct_now_doc_hidden"
version = "0.1.0"
edition = "2021"

[dependencies]
4 changes: 4 additions & 0 deletions test_crates/struct_now_doc_hidden/new/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
struct StayingKnown;

#[doc(hidden)]
pub struct Example;
7 changes: 7 additions & 0 deletions test_crates/struct_now_doc_hidden/old/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
[package]
publish = false
name = "struct_now_doc_hidden"
version = "0.1.0"
edition = "2021"

[dependencies]
3 changes: 3 additions & 0 deletions test_crates/struct_now_doc_hidden/old/src/lib.rs
View file
Open in desktop
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These test cases are fine, but please do try to think of some more edge cases to test for. Simple lints like this are great for practicing those skills!

One trick to help you think of test cases that is called "mutation testing." Take the correct lint you've implemented, and intentionally introduce a bug into it: for example, delete a filter clause, change a filter operator, or add an unnecessary filter or edge traversal somewhere. Then run the tests and see if they catch the bug.

You know you have good test coverage when no matter what bug you introduce, the tests always catch it.

After some practice, you'll be able to run this process "in your head" without actually modifying the lint, and you'll be able to directly write sufficient test cases to catch most reasonable bugs. At the moment, I think there are several plausible ways to accidentally mis-implement this lint that I don't think our test suite as a whole will catch.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really good point, I went ahead and tried to get rid of some lines in the lint which actually ended up being optional entirely :)

In terms of tests, I added a bunch more tests that should make it a lot harder to mis-implement this rule.

Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
struct StayingKnown;
u9g marked this conversation as resolved.
Show resolved Hide resolved

pub struct Example;
46 changes: 46 additions & 0 deletions test_outputs/struct_now_doc_hidden.output.ron
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
{
"./test_crates/struct_now_doc_hidden/": [
{
"path": List([
String("struct_now_doc_hidden"),
String("Example"),
]),
"span_begin_line": Uint64(4),
"span_filename": String("src/lib.rs"),
"struct_name": String("Example"),
"struct_type": String("unit"),
},
],
"./test_crates/type_hidden_from_public_api/": [
{
"path": List([
String("type_hidden_from_public_api"),
String("ExamplePlainStruct"),
]),
"span_begin_line": Uint64(2),
"span_filename": String("src/lib.rs"),
"struct_name": String("ExamplePlainStruct"),
"struct_type": String("plain"),
},
{
"path": List([
String("type_hidden_from_public_api"),
String("ExampleTupleStruct"),
]),
"span_begin_line": Uint64(7),
"span_filename": String("src/lib.rs"),
"struct_name": String("ExampleTupleStruct"),
"struct_type": String("tuple"),
},
{
"path": List([
String("type_hidden_from_public_api"),
String("ExampleUnitStruct"),
]),
"span_begin_line": Uint64(10),
"span_filename": String("src/lib.rs"),
"struct_name": String("ExampleUnitStruct"),
"struct_type": String("unit"),
},
],
}
u9g marked this conversation as resolved.
Show resolved Hide resolved
Loading