Add union pub field now doc hidden lint (#844)

* adds new lint for pub fields in unions being anotated with doc(hidden)

* better documentation on duplicated behavior

* corrects windows slash issues

* Update src/lints/union_pub_field_now_doc_hidden.ron

---------

Co-authored-by: Predrag Gruevski <2348618+obi1kenobi@users.noreply.github.com>

src/lints/union_pub_field_now_doc_hidden.ron

@@ -0,0 +1,67 @@
+SemverQuery(
+    id: "union_pub_field_now_doc_hidden",
+    human_readable_name: "pub union field is now #[doc(hidden)]",
+    description: "A pub union field is now marked #[doc(hidden)] and is no longer part of the public API.",
+    required_update: Major,
+    lint_level: Deny,
+    reference_link: Some("https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html#hidden"),
+    query: r#"
+    {
+        CrateDiff {
+            baseline {
+                item {
+                    ... on Union {
+                        visibility_limit @filter(op: "=", value: ["$public"])
+
+                        importable_path {
+                            path @output @tag
+                            public_api @filter(op: "=", value: ["$true"])
+                        }
+
+                        field {
+                            field_name: name @output @tag
+                            public_api_eligible @filter(op: "=", value: ["$true"])
+                        }
+                    }
+                }
+            }
+            current {
+                item {
+                    ... on Union {
+                        visibility_limit @filter(op: "=", value: ["$public"])
+                        union_name: name @output
+                        # It's possible that both the union and its field became `#[doc(hidden)]`.
+                        # This is a rare case where we don't consider the lint on the field
+                        # to be a duplicate lint of the one on the union.
+                        #
+                        # Doc-hiddenness on the union means we can't legally *name* it
+                        # (i.e. import & use it). But if an existing public API returns this union,
+                        # its pub fields can still be public API without naming the union's type.
+                        #
+                        # This is why we don't check whether the union's path is `public_api`
+                        # in this branch of the query.
+                        importable_path {
+                            path @filter(op: "=", value: ["%path"])
+                        }
+
+                        field {
+                            name @filter(op: "=", value: ["%field_name"])
+                            public_api_eligible @filter(op: "!=", value: ["$true"])
+                        }
+
+                        span_: span @optional {
+                            filename @output
+                            begin_line @output
+                        }
+                    }
+                }
+            }
+        }
+    }"#,
+    arguments: {
+        "public": "public",
+        "true": true,
+    },
+    error_message: "A pub field of a pub union is now marked #[doc(hidden)] and is no longer part of the public API.",
+    per_result_error_template: Some("field {{union_name}}.{{field_name}} in file {{span_filename}}:{{span_begin_line}}"),
+)

src/query.rs

@@ -802,6 +802,7 @@ add_lints!(
     union_field_missing,
     union_missing,
     union_now_doc_hidden,
+    union_pub_field_now_doc_hidden,
     unit_struct_changed_kind,
     variant_marked_non_exhaustive,
 );

test_crates/union_pub_field_now_doc_hidden/new/Cargo.toml

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

test_crates/union_pub_field_now_doc_hidden/new/src/lib.rs

@@ -0,0 +1,40 @@
+// shouldn't flag `union_pub_field_now_doc_hidden` rule
+// and flag `union_now_doc_hidden` instead
+#[doc(hidden)]
+pub union MyUnion {
+    f1: u32,
+    f2: f32,
+}
+
+pub union PublicUnionDocHiddenField {
+
+    #[doc(hidden)]
+    pub my_field: i8,
+}
+
+// shouldn't flag, this is just documented with the string "hidden",
+// it's not actually #[doc(hidden)]
+pub union PublicUnionFieldDocumentedWithStringHidden {
+    #[doc = "hidden"]
+    pub f1: u32,
+    f2: f32,
+}
+
+/// Both the union and its field here will become `#[doc(hidden)]`.
+///
+/// This is a rare case where we want to report a lint for both the union and the field.
+/// Doc-hiddenness on the union means we can't legally *name* it (i.e. import & use it).
+/// But if an existing public API returns this union, its pub fields can still be public API
+/// without naming the union's type.
+#[doc(hidden)]
+pub union PublicUnionBothFieldAndUnionDocHidden {
+    #[doc(hidden)]
+    pub f1: u32,
+    f2: f32,
+}
+
+// shouldn't flag
+pub union UnionWithPrivateField {
+    #[doc(hidden)]
+    f1: u32,
+}

test_crates/union_pub_field_now_doc_hidden/old/Cargo.toml

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

test_crates/union_pub_field_now_doc_hidden/old/src/lib.rs

@@ -0,0 +1,22 @@
+pub union MyUnion {
+    f1: u32,
+    f2: f32,
+}
+
+pub union PublicUnionDocHiddenField {
+    pub my_field: i8,
+}
+
+pub union PublicUnionFieldDocumentedWithStringHidden {
+    pub f1: u32,
+    f2: f32,
+}
+
+pub union PublicUnionBothFieldAndUnionDocHidden {
+    pub f1: u32,
+    f2: f32,
+}
+
+pub union UnionWithPrivateField {
+    f1: u32,
+}

test_outputs/union_now_doc_hidden.output.ron

@@ -21,4 +21,24 @@
             "union_name": String("MyUnion"),
         },
     ],
+    "./test_crates/union_pub_field_now_doc_hidden/": [
+        {
+            "path": List([
+                String("union_pub_field_now_doc_hidden"),
+                String("MyUnion"),
+            ]),
+            "span_begin_line": Uint64(4),
+            "span_filename": String("src/lib.rs"),
+            "union_name": String("MyUnion"),
+        },
+        {
+            "path": List([
+                String("union_pub_field_now_doc_hidden"),
+                String("PublicUnionBothFieldAndUnionDocHidden"),
+            ]),
+            "span_begin_line": Uint64(30),
+            "span_filename": String("src/lib.rs"),
+            "union_name": String("PublicUnionBothFieldAndUnionDocHidden"),
+        },
+    ],
 }

test_outputs/union_pub_field_now_doc_hidden.output.ron

@@ -0,0 +1,36 @@
+{
+    "./test_crates/union_now_doc_hidden/": [
+        {
+            "field_name": String("my_field"),
+            "path": List([
+                String("union_now_doc_hidden"),
+                String("PublicUnionHiddenField"),
+            ]),
+            "span_begin_line": Uint64(7),
+            "span_filename": String("src/lib.rs"),
+            "union_name": String("PublicUnionHiddenField"),
+        },
+    ],
+    "./test_crates/union_pub_field_now_doc_hidden/": [
+        {
+            "field_name": String("my_field"),
+            "path": List([
+                String("union_pub_field_now_doc_hidden"),
+                String("PublicUnionDocHiddenField"),
+            ]),
+            "span_begin_line": Uint64(9),
+            "span_filename": String("src/lib.rs"),
+            "union_name": String("PublicUnionDocHiddenField"),
+        },
+        {
+            "field_name": String("f1"),
+            "path": List([
+                String("union_pub_field_now_doc_hidden"),
+                String("PublicUnionBothFieldAndUnionDocHidden"),
+            ]),
+            "span_begin_line": Uint64(30),
+            "span_filename": String("src/lib.rs"),
+            "union_name": String("PublicUnionBothFieldAndUnionDocHidden"),
+        },
+    ],
+}