Add docs to wasmtime-c-api-macros generated methods (bytecodeallian…

…ce#8957) * add docs to c-api-macros generated methods * apply rustfmt
ahaoboy · Jul 15, 2024 · 180b6dd · 180b6dd
1 parent 66dfa36
commit 180b6dd
Showing 1 changed file with 41 additions and 8 deletions.
diff --git a/crates/c-api-macros/src/lib.rs b/crates/c-api-macros/src/lib.rs
@@ -22,8 +22,10 @@ pub fn declare_own(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
     let ty = extract_ident(input);
     let name = ty.to_string();
     let delete = quote::format_ident!("{}_delete", &name[..name.len() - 2]);
+    let docs = format!("Deletes the [`{name}`].");
 
     (quote! {
+        #[doc = #docs]
         #[no_mangle]
         pub extern fn #delete(_: Box<#ty>) {}
     })
@@ -34,11 +36,18 @@ pub fn declare_own(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
 pub fn declare_ty(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
     let ty = extract_ident(input);
     let name = ty.to_string();
-    let copy = quote::format_ident!("{}_copy", &name[..name.len() - 2]);
+    let prefix = &name[..name.len() - 2];
+    let copy = quote::format_ident!("{}_copy", &prefix);
+    let docs = format!(
+        "Creates a new [`{name}`] which matches the provided one.\n\n\
+        The caller is responsible for deleting the returned value via [`{prefix}_delete`].\n\n\
+    "
+    );
 
     (quote! {
         wasmtime_c_api_macros::declare_own!(#ty);
 
+        #[doc = #docs]
         #[no_mangle]
         pub extern fn #copy(src: &#ty) -> Box<#ty> {
             Box::new(src.clone())
@@ -52,39 +61,61 @@ pub fn declare_ref(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
     let ty = extract_ident(input);
     let name = ty.to_string();
     let prefix = &name[..name.len() - 2];
-    let copy = quote::format_ident!("{}_copy", prefix);
     let same = quote::format_ident!("{}_same", prefix);
+    let same_docs = format!(
+        "Returns `true` if the given references are pointing to the same [`{name}`].\n\n\
+        This is not yet supported and aborts the process upon use."
+    );
     let get_host_info = quote::format_ident!("{}_get_host_info", prefix);
+    let get_host_info_docs = format!(
+        "Returns the host information of the [`{name}`].\n\n\
+        This is not yet supported and always returns `NULL`."
+    );
     let set_host_info = quote::format_ident!("{}_set_host_info", prefix);
+    let set_host_info_docs = format!(
+        "Sets the host information of the [`{name}`].\n\n\
+        This is not yet supported and aborts the process upon use."
+    );
     let set_host_info_final = quote::format_ident!("{}_set_host_info_with_finalizer", prefix);
+    let set_host_info_final_docs = format!(
+        "Sets the host information finalizer of the [`{name}`].\n\n\
+        This is not yet supported and aborts the process upon use."
+    );
     let as_ref = quote::format_ident!("{}_as_ref", prefix);
+    let as_ref_docs = format!(
+        "Returns the [`{name}`] as mutable reference.\n\n\
+        This is not yet supported and aborts the process upon use."
+    );
     let as_ref_const = quote::format_ident!("{}_as_ref_const", prefix);
+    let as_ref_const_docs = format!(
+        "Returns the [`{name}`] as immutable reference.\n\n\
+        This is not yet supported and aborts the process upon use."
+    );
 
     (quote! {
-        wasmtime_c_api_macros::declare_own!(#ty);
-
-        #[no_mangle]
-        pub extern fn #copy(src: &#ty) -> Box<#ty> {
-            Box::new(src.clone())
-        }
+        wasmtime_c_api_macros::declare_ty!(#ty);
 
+        #[doc = #same_docs]
         #[no_mangle]
         pub extern fn #same(_a: &#ty, _b: &#ty) -> bool {
             eprintln!("`{}` is not implemented", stringify!(#same));
             std::process::abort();
         }
 
+        #[doc = #get_host_info_docs]
         #[no_mangle]
         pub extern fn #get_host_info(a: &#ty) -> *mut std::os::raw::c_void {
             std::ptr::null_mut()
         }
 
+        #[doc = #set_host_info_docs]
         #[no_mangle]
         pub extern fn #set_host_info(a: &#ty, info: *mut std::os::raw::c_void) {
             eprintln!("`{}` is not implemented", stringify!(#set_host_info));
             std::process::abort();
         }
 
+        #[doc = #set_host_info_final_docs]
         #[no_mangle]
         pub extern fn #set_host_info_final(
             a: &#ty,
@@ -95,12 +126,14 @@ pub fn declare_ref(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
             std::process::abort();
         }
 
+        #[doc = #as_ref_docs]
         #[no_mangle]
         pub extern fn #as_ref(a: &#ty) -> Box<crate::wasm_ref_t> {
             eprintln!("`{}` is not implemented", stringify!(#as_ref));
             std::process::abort();
         }
 
+        #[doc = #as_ref_const_docs]
         #[no_mangle]
         pub extern fn #as_ref_const(a: &#ty) -> Box<crate::wasm_ref_t> {
             eprintln!("`{}` is not implemented", stringify!(#as_ref_const));