Safety doc for FFI tables load constructor

Author: Bromeon

godot-codegen/src/generator/extension_interface.rs

@@ -12,7 +12,7 @@ use proc_macro2::{Ident, Literal, TokenStream};
 use quote::quote;
 use regex::Regex;
 
-use crate::util::ident;
+use crate::util::{ident, make_load_safety_doc};
 use crate::SubmitFn;
 
 pub fn generate_sys_interface_file(
@@ -77,15 +77,14 @@ fn generate_proc_address_funcs(h_path: &Path) -> TokenStream {
     }
 
     // Do not derive Copy -- even though the struct is bitwise-copyable, this is rarely needed and may point to an error.
+    let safety_doc = make_load_safety_doc();
     let code = quote! {
         pub struct GDExtensionInterface {
             #( #fptr_decls )*
         }
 
         impl GDExtensionInterface {
-            // TODO: Figure out the right safety preconditions. This currently does not have any because incomplete safety docs
-            // can cause issues with people assuming they are sufficient.
-            #[allow(clippy::missing_safety_doc)]
+            #safety_doc
             pub(crate) unsafe fn load(
                 get_proc_address: crate::GDExtensionInterfaceGetProcAddress,
             ) -> Self {

godot-codegen/src/generator/method_tables.rs

@@ -16,7 +16,7 @@ use crate::models::domain::{
     BuiltinClass, BuiltinMethod, BuiltinVariant, Class, ClassCodegenLevel, ClassLike, ClassMethod,
     ExtensionApi, FnDirection, Function, TyName,
 };
-use crate::util::ident;
+use crate::util::{ident, make_load_safety_doc};
 use crate::{conv, generator, special_cases, util};
 
 pub fn make_builtin_lifecycle_table(api: &ExtensionApi) -> TokenStream {
@@ -276,6 +276,7 @@ fn make_named_method_table(info: NamedMethodTable) -> TokenStream {
 
     // Assumes that both decls and inits already have a trailing comma.
     // This is necessary because some generators emit multiple lines (statements) per element.
+    let safety_doc = make_load_safety_doc();
     quote! {
         #imports
 
@@ -288,9 +289,7 @@ fn make_named_method_table(info: NamedMethodTable) -> TokenStream {
             pub const CLASS_COUNT: usize = #class_count;
             pub const METHOD_COUNT: usize = #method_count;
 
-            // TODO: Figure out the right safety preconditions. This currently does not have any because incomplete safety docs
-            // can cause issues with people assuming they are sufficient.
-            #[allow(clippy::missing_safety_doc)]
+            #safety_doc
             pub unsafe fn load(
                 #ctor_parameters
             ) -> Self {
@@ -374,6 +373,7 @@ fn make_method_table(info: IndexedMethodTable) -> TokenStream {
 
     // Assumes that inits already have a trailing comma.
     // This is necessary because some generators emit multiple lines (statements) per element.
+    let safety_doc = make_load_safety_doc();
     quote! {
         #imports
 
@@ -387,9 +387,7 @@ fn make_method_table(info: IndexedMethodTable) -> TokenStream {
             pub const CLASS_COUNT: usize = #class_count;
             pub const METHOD_COUNT: usize = #method_count;
 
-            // TODO: Figure out the right safety preconditions. This currently does not have any because incomplete safety docs
-            // can cause issues with people assuming they are sufficient.
-            #[allow(clippy::missing_safety_doc)]
+            #safety_doc
             #unused_attr
             pub unsafe fn load(
                 #ctor_parameters
@@ -440,6 +438,7 @@ fn make_method_table(info: IndexedMethodTable) -> TokenStream {
 
     // Assumes that inits already have a trailing comma.
     // This is necessary because some generators emit multiple lines (statements) per element.
+    let safety_doc = make_load_safety_doc();
     quote! {
         #imports
         use crate::StringCache;
@@ -462,9 +461,7 @@ fn make_method_table(info: IndexedMethodTable) -> TokenStream {
             pub const CLASS_COUNT: usize = #class_count;
             pub const METHOD_COUNT: usize = #method_count;
 
-            // TODO: Figure out the right safety preconditions. This currently does not have any because incomplete safety docs
-            // can cause issues with people assuming they are sufficient.
-            #[allow(clippy::missing_safety_doc)]
+            #safety_doc
             #unused_attr
             pub unsafe fn load() -> Self {
                 // SAFETY: interface and lifecycle tables are initialized at this point, so we can get 'static references to them.

godot-codegen/src/util.rs

@@ -85,6 +85,14 @@ pub fn lifetime(s: &str) -> TokenStream {
     TokenStream::from_iter([tk_apostrophe, tk_lifetime])
 }
 
+pub fn make_load_safety_doc() -> TokenStream {
+    quote! {
+        /// # Safety
+        /// - Must be called exactly once during library initialization.
+        /// - All parameters (dependencies) must have been initialized and valid.
+    }
+}
+
 // This function is duplicated in godot-macros\src\util\mod.rs
 #[rustfmt::skip]
 pub fn safe_ident(s: &str) -> Ident {