diff --git a/src/lints/enum_now_doc_hidden.ron b/src/lints/enum_now_doc_hidden.ron new file mode 100644 index 00000000..3abb7dc2 --- /dev/null +++ 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 index c35e8ed0..7d69eabf 100644 --- 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 new file mode 100644 index 00000000..6ea4d114 --- /dev/null +++ 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 new file mode 100644 index 00000000..e4fb5f9a --- /dev/null +++ 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 new file mode 100644 index 00000000..6ea4d114 --- /dev/null +++ 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 new file mode 100644 index 00000000..50fdc1f5 --- /dev/null +++ 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 index 7f349be7..e4b1a70e 100644 --- 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 index a2b7f884..d72ec553 100644 --- 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 new file mode 100644 index 00000000..2fe8b658 --- /dev/null +++ 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 index 87652937..2d7d7d5b 100644 --- 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 index f1ba11a6..07f697eb 100644 --- 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"), },