implement function_now_doc_hidden lint (#594)

* add function_now_doc_hidden lint

* rename struct_name output field to function_name

* add more test cases that shouldn't flag and fix existing test case

* add pub to prev commit

src/lints/function_now_doc_hidden.ron

@@ -0,0 +1,48 @@
+SemverQuery(
+    id: "function_now_doc_hidden",
+    human_readable_name: "pub function is now #[doc(hidden)]",
+    description: "A pub function 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 Function {
+                        visibility_limit @filter(op: "=", value: ["$public"])
+
+                        importable_path {
+                            path @output @tag
+                            public_api @filter(op: "=", value: ["$true"])
+                        }
+                    }
+                }
+            }
+            current {
+                item {
+                    ... on Function {
+                        visibility_limit @filter(op: "=", value: ["$public"])
+                        function_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 function is now #[doc(hidden)], removing it from the crate's public API.",
+    per_result_error_template: Some("function {{function_name}} in file {{span_filename}}:{{span_begin_line}}"),
+)

src/query.rs

@@ -485,6 +485,7 @@ add_lints!(
     function_const_removed,
     function_missing,
     function_must_use_added,
+    function_now_doc_hidden,
     function_parameter_count_changed,
     function_unsafe_added,
     inherent_method_const_removed,

test_crates/function_now_doc_hidden/new/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+publish = false
+name = "function_now_doc_hidden"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]

test_crates/function_now_doc_hidden/new/src/lib.rs

@@ -0,0 +1,71 @@
+mod MyNonPublicMod {
+    // despite adding #[doc(hidden)], this function is in a
+    // private mod, so it isn't part of the crate's public
+    // api
+    #[doc(hidden)]
+    pub fn my_function() {}
+}
+
+pub mod MyPublicMod {
+    // added #[doc(hidden)], however this function is in a
+    // public mod, so it previously was part of the crate's public api
+    #[doc(hidden)]
+    pub fn my_function() {}
+}
+
+#[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 fn my_function() {}
+}
+
+mod MyNestedNonPublicMod {
+    pub mod PublicInnerMod {
+        // despite adding #[doc(hidden)], this function is in a
+        // private outer mod, so it isn't part of the crate's public
+        // api
+        #[doc(hidden)]
+        pub fn my_function() {}
+    }
+}
+
+pub mod MyNestedPublicMod {
+    pub mod PublicInnerMod {
+        // added #[doc(hidden)], however this function is in a
+        // public mod, so it previously was part of the crate's public api
+        #[doc(hidden)]
+        pub fn my_function() {}
+    }
+}
+
+#[doc(alias = "hidden")] // shouldn't flag, this is just aliased as hidden,
+                         // but it should be #[doc(hidden)]
+pub fn aliased_as_doc_hidden() {}
+
+#[doc(hidden)] // should flag, this is the simplest case of adding #[doc(hidden)] to a pub function.
+pub fn my_function() {}
+
+#[doc(hidden)] // should flag, this is the case of adding #[doc(hidden)] to a pub function with arguments and a return type.
+pub fn my_function_with_types(a: i32, b: i32) -> i32 {}
+
+#[doc(hidden)]
+fn public_function_that_goes_private() {}
+
+#[doc = "hidden"] // shouldn't flag, this is just documented with the string "hidden",
+                  // it's not actually #[doc(hidden)]
+pub fn public_function_documented_with_string_hidden() {}
+
+#[doc(hidden)] // shouldn't flag under the `function_now_doc_hidden` lint,
+               // this is a constant with a function value, not a real function
+pub const MY_FN: fn() = || {};
+
+fn my_private_fn() {
+    #[doc(hidden)] // shouldn't flag because functions aren't hoisted out of nested scopes
+    pub fn my_public_inner_fn_inside_my_private_fn() {}
+}
+
+pub fn my_public_fn() {
+    #[doc(hidden)] // shouldn't flag because functions aren't hoisted out of nested scopes
+    pub fn my_public_inner_fn_inside_my_public_fn() {}
+}

test_crates/function_now_doc_hidden/old/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+publish = false
+name = "function_now_doc_hidden"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]

test_crates/function_now_doc_hidden/old/src/lib.rs

@@ -0,0 +1,44 @@
+mod MyNonPublicMod {
+    pub fn my_function() {}
+}
+
+pub mod MyPublicMod {
+    pub fn my_function() {}
+}
+
+#[doc(hidden)]
+pub mod MyTopLevelDocHiddenMod {
+    pub fn my_function() {}
+}
+
+mod MyNestedNonPublicMod {
+    pub mod PublicInnerMod {
+        pub fn my_function() {}
+    }
+}
+
+pub mod MyNestedPublicMod {
+    pub mod PublicInnerMod {
+        pub fn my_function() {}
+    }
+}
+
+pub fn aliased_as_doc_hidden() {}
+
+pub fn my_function() {}
+
+pub fn my_function_with_types(a: i32, b: i32) -> i32 {}
+
+fn public_function_that_goes_private() {}
+
+pub fn public_function_documented_with_string_hidden() {}
+
+pub const MY_FN: fn() = || {};
+
+fn my_private_fn() {
+    pub fn my_public_inner_fn_inside_my_private_fn() {}
+}
+
+pub fn my_public_fn() {
+    pub fn my_public_inner_fn_inside_my_public_fn() {}
+}

test_outputs/function_now_doc_hidden.output.ron

@@ -0,0 +1,43 @@
+{
+    "./test_crates/function_now_doc_hidden/": [
+        {
+            "path": List([
+                String("function_now_doc_hidden"),
+                String("MyPublicMod"),
+                String("my_function"),
+            ]),
+            "span_begin_line": Uint64(13),
+            "span_filename": String("src/lib.rs"),
+            "function_name": String("my_function"),
+        },
+        {
+            "path": List([
+                String("function_now_doc_hidden"),
+                String("MyNestedPublicMod"),
+                String("PublicInnerMod"),
+                String("my_function"),
+            ]),
+            "span_begin_line": Uint64(38),
+            "span_filename": String("src/lib.rs"),
+            "function_name": String("my_function"),
+        },
+        {
+            "path": List([
+                String("function_now_doc_hidden"),
+                String("my_function"),
+            ]),
+            "span_begin_line": Uint64(47),
+            "span_filename": String("src/lib.rs"),
+            "function_name": String("my_function"),
+        },
+        {
+            "path": List([
+                String("function_now_doc_hidden"),
+                String("my_function_with_types"),
+            ]),
+            "span_begin_line": Uint64(50),
+            "span_filename": String("src/lib.rs"),
+            "function_name": String("my_function_with_types"),
+        },
+    ],
+}