Add: Support #[deprecated] attribute

Cargo.toml

@@ -26,7 +26,7 @@ serde = { version = "1.0.103", default-features = false, features = ["derive"] }
 serde_json = "1.0"
 tempfile = "3"
 toml = "0.5"
-proc-macro2 = "1"
+proc-macro2 = "1.0.60"
 quote = "1"
 heck = "0.4"
 

docs.md

@@ -680,6 +680,23 @@ args = "horizontal"
 # default: nothing is emitted for must_use functions
 must_use = "MUST_USE_FUNC"
 
+# An optional string that should prefix function declarations which have been
+# marked as `#[deprecated]` without note. For instance, "__attribute__((deprecated))"
+# would be a reasonable value if targeting gcc/clang. A more portable solution
+# would involve emitting the name of a macro which you define in a
+# platform-specific way. e.g. "DEPRECATED_FUNC"
+# default: nothing is emitted for deprecated functions
+deprecated = "DEPRECATED_FUNC"
+
+# An optional string that should prefix function declarations which have been
+# marked as `#[deprecated(note = "reason")]`. `{}` will be replaced with the
+# double-quoted string. For instance, "__attribute__((deprecated({})))"
+# would be a reasonable value if targeting gcc/clang. A more portable solution
+# would involve emitting the name of a macro which you define in a
+# platform-specific way. e.g. "DEPRECATED_FUNC_WITH_NOTE(note)"
+# default: nothing is emitted for deprecated functions
+deprecated_with_notes = "DEPRECATED_FUNC_WITH_NOTE"
+
 # An optional string that will be used in the attribute position for functions
 # that don't return (that return `!` in Rust).
 #
@@ -752,6 +769,23 @@ rename_fields = "PascalCase"
 # default: nothing is emitted for must_use structs
 must_use = "MUST_USE_STRUCT"
 
+# An optional string that should come before the name of any struct which has been
+# marked as `#[deprecated]` without note. For instance, "__attribute__((deprecated))"
+# would be a reasonable value if targeting gcc/clang. A more portable solution
+# would involve emitting the name of a macro which you define in a
+# platform-specific way. e.g. "DEPRECATED_STRUCT"
+# default: nothing is emitted for deprecated structs
+deprecated = "DEPRECATED_STRUCT"
+
+# An optional string that should come before the name of any struct which has been
+# marked as `#[deprecated(note = "reason")]`. `{}` will be replaced with the
+# double-quoted string. For instance, "__attribute__((deprecated({})))"
+# would be a reasonable value if targeting gcc/clang. A more portable solution
+# would involve emitting the name of a macro which you define in a
+# platform-specific way. e.g. "DEPRECATED_STRUCT_WITH_NOTE(note)"
+# default: nothing is emitted for deprecated structs
+deprecated_with_notes = "DEPRECATED_STRUCT_WITH_NOTE"
+
 # Whether a Rust type with associated consts should emit those consts inside the
 # type's body. Otherwise they will be emitted trailing and with the type's name
 # prefixed. This does nothing if the target is C, or if
@@ -865,6 +899,23 @@ cast_assert_name = "MOZ_RELEASE_ASSERT"
 # default: nothing is emitted for must_use enums
 must_use = "MUST_USE_ENUM"
 
+# An optional string that should come before the name of any enum which has been
+# marked as `#[deprecated]` without note. For instance, "__attribute__((deprecated))"
+# would be a reasonable value if targeting gcc/clang. A more portable solution
+# would involve emitting the name of a macro which you define in a
+# platform-specific way. e.g. "DEPRECATED_ENUM"
+# default: nothing is emitted for deprecated enums
+deprecated = "DEPRECATED_ENUM"
+
+# An optional string that should come before the name of any enum which has been
+# marked as `#[deprecated(note = "reason")]`. `{}` will be replaced with the
+# double-quoted string. For instance, "__attribute__((deprecated({})))"
+# would be a reasonable value if targeting gcc/clang. A more portable solution
+# would involve emitting the name of a macro which you define in a
+# platform-specific way. e.g. "DEPRECATED_ENUM_WITH_NOTE(note)"
+# default: nothing is emitted for deprecated enums
+deprecated_with_notes = "DEPRECATED_ENUM_WITH_NOTE"
+
 # Whether enums with fields should generate destructors. This exists so that generic
 # enums can be properly instantiated with payloads that are C++ types with
 # destructors. This isn't necessary for structs because C++ has rules to

src/bindgen/cdecl.rs

@@ -40,6 +40,7 @@ struct CDecl {
     type_generic_args: Vec<GenericArgument>,
     declarators: Vec<CDeclarator>,
     type_ctype: Option<DeclarationType>,
+    deprecated: Option<String>,
 }
 
 impl CDecl {
@@ -50,6 +51,7 @@ impl CDecl {
             type_generic_args: Vec::new(),
             declarators: Vec::new(),
             type_ctype: None,
+            deprecated: None,
         }
     }
 
@@ -99,6 +101,7 @@ impl CDecl {
             layout,
             never_return: f.never_return,
         });
+        self.deprecated = f.annotations.deprecated.clone();
         self.build_type(&f.ret, false, config);
     }
 

src/bindgen/config.rs

@@ -425,6 +425,10 @@ pub struct FunctionConfig {
     pub postfix: Option<String>,
     /// The way to annotation this function as #[must_use]
     pub must_use: Option<String>,
+    /// The way to annotation this function as #[deprecated] without notes
+    pub deprecated: Option<String>,
+    /// The way to annotation this function as #[deprecated] with notes
+    pub deprecated_with_note: Option<String>,
     /// The style to layout the args
     pub args: Layout,
     /// The rename rule to apply to function args
@@ -443,6 +447,8 @@ impl Default for FunctionConfig {
             prefix: None,
             postfix: None,
             must_use: None,
+            deprecated: None,
+            deprecated_with_note: None,
             args: Layout::Auto,
             rename_args: RenameRule::None,
             swift_name_macro: None,
@@ -498,6 +504,10 @@ pub struct StructConfig {
     pub associated_constants_in_body: bool,
     /// The way to annotate this struct as #[must_use].
     pub must_use: Option<String>,
+    /// The way to annotation this function as #[deprecated] without notes
+    pub deprecated: Option<String>,
+    /// The way to annotation this function as #[deprecated] with notes
+    pub deprecated_with_note: Option<String>,
 }
 
 impl StructConfig {
@@ -581,6 +591,10 @@ pub struct EnumConfig {
     pub cast_assert_name: Option<String>,
     /// The way to annotation this enum as #[must_use].
     pub must_use: Option<String>,
+    /// The way to annotation this function as #[deprecated] without notes
+    pub deprecated: Option<String>,
+    /// The way to annotation this function as #[deprecated] with notes
+    pub deprecated_with_note: Option<String>,
     /// Whether to generate destructors of tagged enums.
     pub derive_tagged_enum_destructor: bool,
     /// Whether to generate copy-constructors of tagged enums.
@@ -612,6 +626,8 @@ impl Default for EnumConfig {
             derive_mut_casts: false,
             cast_assert_name: None,
             must_use: None,
+            deprecated: None,
+            deprecated_with_note: None,
             derive_tagged_enum_destructor: false,
             derive_tagged_enum_copy_constructor: false,
             derive_tagged_enum_copy_assignment: false,

src/bindgen/ir/annotation.rs

@@ -35,13 +35,15 @@ pub enum AnnotationValue {
 pub struct AnnotationSet {
     annotations: HashMap<String, AnnotationValue>,
     pub must_use: bool,
+    pub deprecated: Option<String>,
 }
 
 impl AnnotationSet {
     pub fn new() -> AnnotationSet {
         AnnotationSet {
             annotations: HashMap::new(),
             must_use: false,
+            deprecated: None,
         }
     }
 
@@ -53,6 +55,10 @@ impl AnnotationSet {
         self.must_use && config.language != Language::Cython
     }
 
+    pub(crate) fn deprecated(&self, config: &Config) -> bool {
+        self.deprecated.is_some() && config.language != Language::Cython
+    }
+
     pub fn load(attrs: &[syn::Attribute]) -> Result<AnnotationSet, String> {
         let lines = attrs.get_comment_lines();
         let lines: Vec<&str> = lines
@@ -68,6 +74,36 @@ impl AnnotationSet {
             .collect();
 
         let must_use = attrs.has_attr_word("must_use");
+        let deprecated = if let Some(note) = attrs.attr_name_value_lookup("deprecated") {
+            Some(note)
+        } else if attrs.has_attr_word("deprecated") {
+            Some("".to_string())
+        } else if let Some(attr) = attrs.iter().find(|attr| {
+            if let Ok(syn::Meta::List(list)) = attr.parse_meta() {
+                list.path.is_ident("deprecated")
+            } else {
+                false
+            }
+        }) {
+            let args: syn::punctuated::Punctuated<syn::MetaNameValue, Token![,]> = attr
+                .parse_args_with(syn::punctuated::Punctuated::parse_terminated)
+                .map_err(|e| format!("Couldn't parse deprecated attribute: {}", e.to_string()))?;
+            let Some(lit) = args
+                .iter()
+                .find(|arg| arg.path.is_ident("note"))
+                .map(|arg| &arg.lit)
+            else {
+                return Err("Couldn't parse deprecated attribute: no `note` field".to_string());
+            };
+
+            if let syn::Lit::Str(lit) = lit {
+                Some(lit.value())
+            } else {
+                return Err("deprecated attribute must be a string".to_string());
+            }
+        } else {
+            None
+        };
 
         let mut annotations = HashMap::new();
 
@@ -118,6 +154,7 @@ impl AnnotationSet {
         Ok(AnnotationSet {
             annotations,
             must_use,
+            deprecated,
         })
     }
 

src/bindgen/ir/enumeration.rs

@@ -753,7 +753,22 @@ impl Enum {
                 if let Some(prim) = size {
                     // If we need to specify size, then we have no choice but to create a typedef,
                     // so `config.style` is not respected.
-                    write!(out, "enum {}", tag_name);
+                    write!(out, "enum");
+                    if self.annotations.deprecated(config) {
+                        let note = self.annotations.deprecated.as_ref().unwrap();
+                        if note.is_empty() {
+                            if let Some(ref anno) = config.structure.deprecated {
+                                write!(out, " {}", anno);
+                            }
+                        } else if let Some(ref anno) = config.structure.deprecated_with_note {
+                            write!(
+                                out,
+                                " {}",
+                                anno.replace("{}", format!("{:?}", note).as_str())
+                            );
+                        }
+                    }
+                    write!(out, " {}", tag_name);
 
                     if config.cpp_compatible_c() {
                         out.new_line();
@@ -769,6 +784,20 @@ impl Enum {
                         out.write("typedef ");
                     }
                     out.write("enum");
+                    if self.annotations.deprecated(config) {
+                        let note = self.annotations.deprecated.as_ref().unwrap();
+                        if note.is_empty() {
+                            if let Some(ref anno) = config.structure.deprecated {
+                                write!(out, " {}", anno);
+                            }
+                        } else if let Some(ref anno) = config.structure.deprecated_with_note {
+                            write!(
+                                out,
+                                " {}",
+                                anno.replace("{}", format!("{:?}", note).as_str())
+                            );
+                        }
+                    }
                     if config.style.generate_tag() {
                         write!(out, " {}", tag_name);
                     }
@@ -787,6 +816,21 @@ impl Enum {
                     }
                 }
 
+                if self.annotations.deprecated(config) {
+                    let note = self.annotations.deprecated.as_ref().unwrap();
+                    if note.is_empty() {
+                        if let Some(ref anno) = config.structure.deprecated {
+                            write!(out, " {}", anno);
+                        }
+                    } else if let Some(ref anno) = config.structure.deprecated_with_note {
+                        write!(
+                            out,
+                            " {}",
+                            anno.replace("{}", format!("{:?}", note).as_str())
+                        );
+                    }
+                }
+
                 write!(out, " {}", tag_name);
                 if let Some(prim) = size {
                     write!(out, " : {}", prim);
@@ -865,6 +909,17 @@ impl Enum {
             }
         }
 
+        if self.annotations.deprecated(config) {
+            let note = self.annotations.deprecated.as_ref().unwrap();
+            if note.is_empty() {
+                if let Some(ref anno) = config.structure.deprecated {
+                    write!(out, " {}", anno);
+                }
+            } else if let Some(ref anno) = config.structure.deprecated_with_note {
+                write!(out, " {}", anno);
+            }
+        }
+
         if config.language != Language::C || config.style.generate_tag() {
             write!(out, " {}", self.export_name());
         }

src/bindgen/ir/function.rs

@@ -241,6 +241,20 @@ impl Source for Function {
                         write!(out, "{} ", anno);
                     }
                 }
+                if func.annotations.deprecated(config) {
+                    let note = func.annotations.deprecated.as_ref().unwrap();
+                    if note.is_empty() {
+                        if let Some(ref anno) = config.function.deprecated {
+                            write!(out, "{} ", anno);
+                        }
+                    } else if let Some(ref anno) = config.function.deprecated_with_note {
+                        write!(
+                            out,
+                            "{} ",
+                            anno.replace("{}", format!("{:?}", note).as_str())
+                        );
+                    }
+                }
             }
             cdecl::write_func(out, func, Layout::Horizontal, config);
 
@@ -284,6 +298,22 @@ impl Source for Function {
                         out.new_line();
                     }
                 }
+                if func.annotations.deprecated(config) {
+                    let note = func.annotations.deprecated.as_ref().unwrap();
+                    if note.is_empty() {
+                        if let Some(ref anno) = config.function.deprecated {
+                            write!(out, "{}", anno);
+                            out.new_line();
+                        }
+                    } else if let Some(ref anno) = config.function.deprecated_with_note {
+                        write!(
+                            out,
+                            "{}",
+                            anno.replace("{}", format!("{:?}", note).as_str())
+                        );
+                        out.new_line();
+                    }
+                }
             }
             cdecl::write_func(out, func, Layout::Vertical, config);
             if !func.extern_decl {

src/bindgen/ir/structure.rs

@@ -455,6 +455,20 @@ impl Source for Struct {
                 write!(out, " {}", anno);
             }
         }
+        if self.annotations.deprecated(config) {
+            let note = self.annotations.deprecated.as_ref().unwrap();
+            if note.is_empty() {
+                if let Some(ref anno) = config.structure.deprecated {
+                    write!(out, " {}", anno);
+                }
+            } else if let Some(ref anno) = config.structure.deprecated_with_note {
+                write!(
+                    out,
+                    " {}",
+                    anno.replace("{}", format!("{:?}", note).as_str())
+                );
+            }
+        }
 
         if config.language != Language::C || config.style.generate_tag() {
             write!(out, " {}", self.export_name());