implement struct_now_doc_hidden lint (#587)

* implement struct_now_doc_hidden lint * Update src/lints/struct_now_doc_hidden.ron Co-authored-by: Predrag Gruevski <[email protected]> * no need to filter on struct type * Update src/lints/struct_now_doc_hidden.ron Co-authored-by: Predrag Gruevski <[email protected]> * Update src/lints/struct_now_doc_hidden.ron Co-authored-by: Predrag Gruevski <[email protected]> * fix no end new line * remove struct_type from expected output * add struct-in-mod tests * add even more nested mods * add mispelled doc hidden and hidden field to tests * add better explanation comment * add test for adding doc hidden to a now-private struct * add comment to test * add test for possible doc hidden mistake * replace invalid test with valid test of alias of hidden --------- Co-authored-by: Predrag Gruevski <[email protected]>
obi1kenobi · Nov 28, 2023 · 438f6d8 · 438f6d8
1 parent 0b10340
commit 438f6d8
Show file tree

Hide file tree

Showing 8 changed files with 225 additions and 0 deletions.
diff --git a/src/lints/struct_now_doc_hidden.ron b/src/lints/struct_now_doc_hidden.ron
@@ -0,0 +1,48 @@
+SemverQuery(
+    id: "struct_now_doc_hidden",
+    human_readable_name: "pub struct is now #[doc(hidden)]",
+    description: "A pub struct is now marked #[doc(hidden)] and is thus no longer part of the public API.",
+    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"])
+
+                        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
+
+                        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 pub struct is now #[doc(hidden)], removing it from the crate's public API.",
+    per_result_error_template: Some("struct {{struct_name}} in file {{span_filename}}:{{span_begin_line}}"),
+)
diff --git a/src/query.rs b/src/query.rs
@@ -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,

diff --git a/test_crates/struct_now_doc_hidden/new/Cargo.toml b/test_crates/struct_now_doc_hidden/new/Cargo.toml
@@ -0,0 +1,7 @@
+[package]
+publish = false
+name = "struct_now_doc_hidden"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
diff --git a/test_crates/struct_now_doc_hidden/new/src/lib.rs b/test_crates/struct_now_doc_hidden/new/src/lib.rs
@@ -0,0 +1,55 @@
+mod MyNonPublicMod {
+    // despite adding #[doc(hidden)], this struct is in a
+    // private mod, so it isn't part of the crate's public
+    // api
+    #[doc(hidden)]
+    pub struct MyStruct;
+}
+
+pub mod MyPublicMod {
+    // added #[doc(hidden)], however this struct is in a
+    // public mod, so it is part of the crate's public api
+    #[doc(hidden)]
+    pub struct MyStruct;
+}
+
+mod MyNestedNonPublicMod {
+    pub mod PublicInnerStruct {
+        // despite adding #[doc(hidden)], this struct is in a
+        // private outer mod, so it isn't part of the crate's public
+        // api
+        #[doc(hidden)]
+        pub struct MyStruct;
+    }
+}
+
+pub mod MyNestedPublicMod {
+    pub mod PublicInnerStruct {
+        // added #[doc(hidden)], however this struct is in a
+        // public mod, so it is part of the crate's public api
+        #[doc(hidden)]
+        pub struct MyStruct;
+    }
+}
+
+#[doc(alias = "hidden")] // shouldn't flag, this is just aliased as hidden,
+                         // but it should be #[doc(hidden)]
+pub struct AliasedAsDocHidden;
+
+#[doc(hidden)] // should flag, this is the simplest case of adding #[doc(hidden)] to a pub struct.
+pub struct Example;
+
+pub struct PublicStructHiddenField {
+    // shouldn't flag `struct_now_doc_hidden` rule
+    // as this is a field that's hidden,
+    // not the entire struct
+    #[doc(hidden)]
+    pub my_field: i8,
+}
+
+#[doc(hidden)]
+struct PublicStructThatGoesPrivate;
+
+#[doc = "hidden"] // shouldn't flag, this is just documented with the string "hidden",
+                  // it's not actually #[doc(hidden)]
+pub struct PublicStructDocumentedWithStringHidden;
diff --git a/test_crates/struct_now_doc_hidden/old/Cargo.toml b/test_crates/struct_now_doc_hidden/old/Cargo.toml
@@ -0,0 +1,7 @@
+[package]
+publish = false
+name = "struct_now_doc_hidden"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
diff --git a/test_crates/struct_now_doc_hidden/old/src/lib.rs b/test_crates/struct_now_doc_hidden/old/src/lib.rs
@@ -0,0 +1,31 @@
+mod MyNonPublicMod {
+    pub struct MyStruct;
+}
+
+pub mod MyPublicMod {
+    pub struct MyStruct;
+}
+
+pub struct AliasedAsDocHidden;
+
+pub struct Example;
+
+pub struct PublicStructHiddenField {
+    pub my_field: i8,
+}
+
+mod MyNestedNonPublicMod {
+    pub mod PublicInnerStruct {
+        pub struct MyStruct;
+    }
+}
+
+pub mod MyNestedPublicMod {
+    pub mod PublicInnerStruct {
+        pub struct MyStruct;
+    }
+}
+
+pub struct PublicStructThatGoesPrivate;
+
+pub struct PublicStructDocumentedWithStringHidden;
diff --git a/test_outputs/struct_missing.output.ron b/test_outputs/struct_missing.output.ron
@@ -84,6 +84,19 @@
             "visibility_limit": String("public"),
         },
     ],
+    "./test_crates/struct_now_doc_hidden/": [
+        {
+            "name": String("PublicStructThatGoesPrivate"),
+            "path": List([
+                String("struct_now_doc_hidden"),
+                String("PublicStructThatGoesPrivate"),
+            ]),
+            "span_begin_line": Uint64(29),
+            "span_filename": String("src/lib.rs"),
+            "struct_type": String("unit"),
+            "visibility_limit": String("public"),
+        },
+    ],
     "./test_crates/struct_pub_field_missing/": [
         {
             "name": String("StructRemoved"),

diff --git a/test_outputs/struct_now_doc_hidden.output.ron b/test_outputs/struct_now_doc_hidden.output.ron
@@ -0,0 +1,63 @@
+{
+    "./test_crates/struct_now_doc_hidden/": [
+        {
+            "path": List([
+                String("struct_now_doc_hidden"),
+                String("MyPublicMod"),
+                String("MyStruct"),
+            ]),
+            "span_begin_line": Uint64(13),
+            "span_filename": String("src/lib.rs"),
+            "struct_name": String("MyStruct"),
+        },
+        {
+            "path": List([
+                String("struct_now_doc_hidden"),
+                String("MyNestedPublicMod"),
+                String("PublicInnerStruct"),
+                String("MyStruct"),
+            ]),
+            "span_begin_line": Uint64(31),
+            "span_filename": String("src/lib.rs"),
+            "struct_name": String("MyStruct"),
+        },
+        {
+            "path": List([
+                String("struct_now_doc_hidden"),
+                String("Example"),
+            ]),
+            "span_begin_line": Uint64(40),
+            "span_filename": String("src/lib.rs"),
+            "struct_name": String("Example"),
+        },
+    ],
+    "./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"),
+        },
+        {
+            "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"),
+        },
+        {
+            "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"),
+        },
+    ],
+}