implement enum_now_doc_hidden lint (#593)

* implement rule * Update test_crates/enum_now_doc_hidden/new/src/lib.rs Co-authored-by: Predrag Gruevski <[email protected]> * rename PublicInnerStruct to PublicInnerMod * change comment everywhere else * add doc hidden outer mod test to enum/struct test --------- Co-authored-by: Predrag Gruevski <[email protected]>
obi1kenobi · Dec 5, 2023 · c740fdf · c740fdf
1 parent 74b08ab
commit c740fdf
Show file tree

Hide file tree

Showing 11 changed files with 282 additions and 10 deletions.
diff --git a/src/lints/enum_now_doc_hidden.ron b/src/lints/enum_now_doc_hidden.ron
@@ -0,0 +1,48 @@
+SemverQuery(
+    id: "enum_now_doc_hidden",
+    human_readable_name: "pub enum is now #[doc(hidden)]",
+    description: "A pub enum 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 Enum {
+                        visibility_limit @filter(op: "=", value: ["$public"])
+
+                        importable_path {
+                            path @output @tag
+                            public_api @filter(op: "=", value: ["$true"])
+                        }
+                    }
+                }
+            }
+            current {
+                item {
+                    ... on Enum {
+                        visibility_limit @filter(op: "=", value: ["$public"])
+                        enum_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 enum is now #[doc(hidden)], removing it from the crate's public API.",
+    per_result_error_template: Some("enum {{enum_name}} in file {{span_filename}}:{{span_begin_line}}"),
+)
diff --git a/src/query.rs b/src/query.rs
@@ -474,6 +474,7 @@ add_lints!(
     enum_marked_non_exhaustive,
     enum_missing,
     enum_must_use_added,
+    enum_now_doc_hidden,
     enum_repr_c_removed,
     enum_repr_int_changed,
     enum_repr_int_removed,

diff --git a/test_crates/enum_now_doc_hidden/new/Cargo.toml b/test_crates/enum_now_doc_hidden/new/Cargo.toml
@@ -0,0 +1,7 @@
+[package]
+publish = false
+name = "enum_now_doc_hidden"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
diff --git a/test_crates/enum_now_doc_hidden/new/src/lib.rs b/test_crates/enum_now_doc_hidden/new/src/lib.rs
@@ -0,0 +1,92 @@
+mod MyNonPublicMod {
+    // despite adding #[doc(hidden)], this enum is in a
+    // private mod, so it isn't part of the crate's public
+    // api
+    #[doc(hidden)]
+    pub enum MyEnum {
+        A,
+    }
+}
+
+pub mod MyPublicMod {
+    // added #[doc(hidden)], however this enum is in a
+    // public mod, so it previously was part of the crate's public api
+    #[doc(hidden)]
+    pub enum MyEnum {
+        A,
+    }
+}
+
+#[doc(hidden)]
+pub mod MyTopLevelDocHiddenMod {
+    #[doc(hidden)] // this shouldn't flag, as it's a top level mod
+                   // was never part of the public api of the crate
+    pub enum MyEnumThatIsNowDocHidden {
+        A,
+    }
+}
+
+mod MyNestedNonPublicMod {
+    pub mod PublicInnerMod {
+        // despite adding #[doc(hidden)], this enum is in a
+        // private outer mod, so it isn't part of the crate's public
+        // api
+        #[doc(hidden)]
+        pub enum MyEnum {
+            A,
+        }
+    }
+}
+
+pub mod MyNestedPublicMod {
+    pub mod PublicInnerMod {
+        // added #[doc(hidden)], however this enum is in a
+        // public mod, so it previously was part of the crate's public api
+        #[doc(hidden)]
+        pub enum MyEnum {
+            A,
+        }
+    }
+}
+
+#[doc(alias = "hidden")] // shouldn't flag, this is just aliased as hidden,
+                         // but it should be #[doc(hidden)]
+pub enum AliasedAsDocHidden {
+    A,
+}
+
+#[doc(hidden)] // should flag, this is the simplest case of adding #[doc(hidden)] to a pub enum.
+pub enum Example {
+    A,
+}
+
+pub enum PublicEnumHiddenVariant {
+    // shouldn't flag `enum_now_doc_hidden` rule
+    // as this is a field that's hidden,
+    // not the entire struct
+    #[doc(hidden)]
+    A,
+    B,
+}
+
+pub enum PublicEnumHiddenStructFieldOnVariant {
+    // shouldn't flag `enum_now_doc_hidden` rule
+    // as this is a field that's hidden on a struct variant,
+    // not the entire enum
+    A {
+        #[doc(hidden)]
+        a: u8,
+    },
+    B,
+}
+
+#[doc(hidden)]
+enum PublicEnumThatGoesPrivate {
+    A,
+}
+
+#[doc = "hidden"] // shouldn't flag, this is just documented with the string "hidden",
+                  // it's not actually #[doc(hidden)]
+pub enum PublicEnumDocumentedWithStringHidden {
+    A,
+}
diff --git a/test_crates/enum_now_doc_hidden/old/Cargo.toml b/test_crates/enum_now_doc_hidden/old/Cargo.toml
@@ -0,0 +1,7 @@
+[package]
+publish = false
+name = "enum_now_doc_hidden"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
diff --git a/test_crates/enum_now_doc_hidden/old/src/lib.rs b/test_crates/enum_now_doc_hidden/old/src/lib.rs
@@ -0,0 +1,60 @@
+mod MyNonPublicMod {
+    pub enum MyEnum {
+        A,
+    }
+}
+
+pub mod MyPublicMod {
+    pub enum MyEnum {
+        A,
+    }
+}
+
+#[doc(hidden)]
+pub mod MyTopLevelDocHiddenMod {
+    pub enum MyEnumThatIsNowDocHidden {
+        A,
+    }
+}
+
+mod MyNestedNonPublicMod {
+    pub mod PublicInnerMod {
+        pub enum MyEnum {
+            A,
+        }
+    }
+}
+
+pub mod MyNestedPublicMod {
+    pub mod PublicInnerMod {
+        pub enum MyEnum {
+            A,
+        }
+    }
+}
+
+pub enum AliasedAsDocHidden {
+    A,
+}
+
+pub enum Example {
+    A,
+}
+
+pub enum PublicEnumHiddenVariant {
+    A,
+    B,
+}
+
+pub enum PublicEnumHiddenStructFieldOnVariant {
+    A { a: u8 },
+    B,
+}
+
+enum PublicEnumThatGoesPrivate {
+    A,
+}
+
+pub enum PublicEnumDocumentedWithStringHidden {
+    A,
+}
diff --git a/test_crates/struct_now_doc_hidden/new/src/lib.rs b/test_crates/struct_now_doc_hidden/new/src/lib.rs
@@ -8,13 +8,20 @@ mod MyNonPublicMod {
 
 pub mod MyPublicMod {
     // added #[doc(hidden)], however this struct is in a
-    // public mod, so it is part of the crate's public api
+    // public mod, so it previously was part of the crate's public api
     #[doc(hidden)]
     pub struct MyStruct;
 }
 
+#[doc(hidden)]
+pub mod MyTopLevelDocHiddenMod {
+    #[doc(hidden)] // this shouldn't flag, as it's a top level mod
+                   // was never part of the public api of the crate
+    pub struct MyStructThatIsNowDocHidden;
+}
+
 mod MyNestedNonPublicMod {
-    pub mod PublicInnerStruct {
+    pub mod PublicInnerMod {
         // despite adding #[doc(hidden)], this struct is in a
         // private outer mod, so it isn't part of the crate's public
         // api
@@ -24,9 +31,9 @@ mod MyNestedNonPublicMod {
 }
 
 pub mod MyNestedPublicMod {
-    pub mod PublicInnerStruct {
+    pub mod PublicInnerMod {
         // added #[doc(hidden)], however this struct is in a
-        // public mod, so it is part of the crate's public api
+        // public mod, so it previously was part of the crate's public api
         #[doc(hidden)]
         pub struct MyStruct;
     }

diff --git a/test_crates/struct_now_doc_hidden/old/src/lib.rs b/test_crates/struct_now_doc_hidden/old/src/lib.rs
@@ -14,14 +14,19 @@ pub struct PublicStructHiddenField {
     pub my_field: i8,
 }
 
+#[doc(hidden)]
+pub mod MyTopLevelDocHiddenMod {
+    pub struct MyStructThatIsNowDocHidden;
+}
+
 mod MyNestedNonPublicMod {
-    pub mod PublicInnerStruct {
+    pub mod PublicInnerMod {
         pub struct MyStruct;
     }
 }
 
 pub mod MyNestedPublicMod {
-    pub mod PublicInnerStruct {
+    pub mod PublicInnerMod {
         pub struct MyStruct;
     }
 }

diff --git a/test_outputs/enum_now_doc_hidden.output.ron b/test_outputs/enum_now_doc_hidden.output.ron
@@ -0,0 +1,45 @@
+{
+    "./test_crates/enum_now_doc_hidden/": [
+        {
+            "enum_name": String("MyEnum"),
+            "path": List([
+                String("enum_now_doc_hidden"),
+                String("MyPublicMod"),
+                String("MyEnum"),
+            ]),
+            "span_begin_line": Uint64(15),
+            "span_filename": String("src/lib.rs"),
+        },
+        {
+            "enum_name": String("MyEnum"),
+            "path": List([
+                String("enum_now_doc_hidden"),
+                String("MyNestedPublicMod"),
+                String("PublicInnerMod"),
+                String("MyEnum"),
+            ]),
+            "span_begin_line": Uint64(46),
+            "span_filename": String("src/lib.rs"),
+        },
+        {
+            "enum_name": String("Example"),
+            "path": List([
+                String("enum_now_doc_hidden"),
+                String("Example"),
+            ]),
+            "span_begin_line": Uint64(59),
+            "span_filename": String("src/lib.rs"),
+        },
+    ],
+    "./test_crates/type_hidden_from_public_api/": [
+        {
+            "enum_name": String("ExampleEnum"),
+            "path": List([
+                String("type_hidden_from_public_api"),
+                String("ExampleEnum"),
+            ]),
+            "span_begin_line": Uint64(13),
+            "span_filename": String("src/lib.rs"),
+        },
+    ],
+}
diff --git a/test_outputs/struct_missing.output.ron b/test_outputs/struct_missing.output.ron
@@ -91,7 +91,7 @@
                 String("struct_now_doc_hidden"),
                 String("PublicStructThatGoesPrivate"),
             ]),
-            "span_begin_line": Uint64(29),
+            "span_begin_line": Uint64(34),
             "span_filename": String("src/lib.rs"),
             "struct_type": String("unit"),
             "visibility_limit": String("public"),

diff --git a/test_outputs/struct_now_doc_hidden.output.ron b/test_outputs/struct_now_doc_hidden.output.ron
@@ -14,10 +14,10 @@
             "path": List([
                 String("struct_now_doc_hidden"),
                 String("MyNestedPublicMod"),
-                String("PublicInnerStruct"),
+                String("PublicInnerMod"),
                 String("MyStruct"),
             ]),
-            "span_begin_line": Uint64(31),
+            "span_begin_line": Uint64(38),
             "span_filename": String("src/lib.rs"),
             "struct_name": String("MyStruct"),
         },
@@ -26,7 +26,7 @@
                 String("struct_now_doc_hidden"),
                 String("Example"),
             ]),
-            "span_begin_line": Uint64(40),
+            "span_begin_line": Uint64(47),
             "span_filename": String("src/lib.rs"),
             "struct_name": String("Example"),
         },