byondapi-sys improvements and ffi documentation

.gitattributes

@@ -0,0 +1,2 @@
+*.h		text	linguist-vendored
+*.hpp	text	linguist-vendored

crates/byondapi-sys/Cargo.toml

@@ -17,12 +17,13 @@ default-target = "i686-unknown-linux-gnu"
 targets = []                              # Do not build the doc with any other target than the default.
 
 [dependencies]
-libloading = "0.8.1"
+libloading = "0.8"
 
 [build-dependencies]
-bindgen = "0.69.1"
-rustc_version = "0.4.0"
-walkdir = "2.4.0"
+bindgen = "0.69"
+rustc_version = "0.4"
+walkdir = "2"
+doxygen-rs = "0.4"
 
 [features]
 default = ["byond-515-1621"]

crates/byondapi-sys/build.rs

@@ -1,3 +1,4 @@
+use bindgen::callbacks::ParseCallbacks;
 use std::path::{Path, PathBuf};
 
 fn main() {
@@ -43,22 +44,34 @@ fn copy_wrapper(lib_dir: &Path) -> PathBuf {
 fn generate_all() {
     let out_dir = PathBuf::from(std::env::var("OUT_DIR").expect("OUT_DIR not defined"));
 
-    get_headers().iter().for_each(|(path, version)| {
-        let target = out_dir.join("byondapi.h");
-        std::fs::copy(path, target).expect("Failed to copy to out_dir");
-        let wrapper = copy_wrapper(&out_dir);
+    get_headers()
+        .into_iter()
+        .for_each(|(path, (major, minor))| {
+            let target = out_dir.join("byondapi.h");
+            std::fs::copy(path, target).expect("Failed to copy to out_dir");
+            let wrapper = copy_wrapper(&out_dir);
 
-        let builder = bindgen::Builder::default()
-            .header(wrapper.to_string_lossy())
-            .dynamic_library_name("ByondApi")
-            .dynamic_link_require_all(true)
-            // Also make headers included by main header dependencies of the build
-            .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()));
+            let builder = bindgen::Builder::default()
+                .header(wrapper.to_string_lossy())
+                .dynamic_library_name("ByondApi")
+                .dynamic_link_require_all(true)
+                // Also make headers included by main header dependencies of the build
+                .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))
+                .parse_callbacks(Box::new(DoxygenCallbacks));
 
-        builder
-            .generate()
-            .expect("Unable to generate bindings")
-            .write_to_file(out_dir.join(format!("bindings_{}_{}.rs", version.0, version.1)))
-            .expect("Couldn't write bindings!");
-    });
+            builder
+                .generate()
+                .expect("Unable to generate bindings")
+                .write_to_file(out_dir.join(format!("bindings_{major}_{minor}.rs")))
+                .expect("Couldn't write bindings!");
+        });
+}
+
+#[derive(Debug)]
+struct DoxygenCallbacks;
+
+impl ParseCallbacks for DoxygenCallbacks {
+    fn process_comment(&self, comment: &str) -> Option<String> {
+        Some(doxygen_rs::transform(comment))
+    }
 }

crates/byondapi-sys/src/lib.rs

@@ -1,9 +1,11 @@
 // Ignore style warnings for for byondapi-c bindings
-#![allow(non_upper_case_globals)]
-#![allow(non_camel_case_types)]
-#![allow(non_snake_case)]
-#![allow(clippy::missing_safety_doc)]
-use std::ffi::c_char;
+#![allow(
+    clippy::missing_safety_doc,
+    non_upper_case_globals,
+    non_camel_case_types,
+    non_snake_case
+)]
+use std::ops::Deref;
 
 #[cfg(not(target_pointer_width = "32"))]
 compile_error!("BYOND API only functions with 32-bit targets");
@@ -15,12 +17,15 @@ compile_error!("BYOND API only functions on x86 targets");
 compile_error!("BYOND API only supports Windows and Linux");
 
 // Include byondapi-c bindings (generated by build.rs)
-#[allow(dead_code)]
+#[allow(dead_code, rustdoc::broken_intra_doc_links)]
 mod byond_rawbind {
     #[cfg(feature = "byond-515-1621")]
     include!(concat!(env!("OUT_DIR"), "/bindings_515_1621.rs"));
 }
 
+#[cfg(doc)]
+pub use byond_rawbind::ByondApi as RawByondApi;
+
 /// we must simply hope this never changes
 mod version {
     use super::byond_rawbind::u4c;
@@ -66,6 +71,15 @@ impl ByondApi {
     }
 }
 
+impl Deref for ByondApi {
+    type Target = byond_rawbind::ByondApi;
+
+    #[inline]
+    fn deref(&self) -> &Self::Target {
+        &self.internal
+    }
+}
+
 // Stabilized types
 pub use byond_rawbind::s1c;
 pub use byond_rawbind::s1cMAX;
@@ -87,255 +101,3 @@ pub use byond_rawbind::ByondValueData;
 pub use byond_rawbind::ByondValueType;
 pub use byond_rawbind::CByondValue;
 pub use byond_rawbind::CByondXYZ;
-
-// Stabilized functions
-impl ByondApi {
-    pub unsafe fn Byond_LastError(&self) -> *const c_char {
-        self.internal.Byond_LastError()
-    }
-    pub unsafe fn Byond_GetVersion(&self, version: *mut u4c, build: *mut u4c) {
-        self.internal.Byond_GetVersion(version, build)
-    }
-    pub unsafe fn Byond_GetDMBVersion(&self) -> u4c {
-        self.internal.Byond_GetDMBVersion()
-    }
-    pub unsafe fn ByondValue_Clear(&self, v: *mut CByondValue) {
-        self.internal.ByondValue_Clear(v)
-    }
-    pub unsafe fn ByondValue_Type(&self, v: *const CByondValue) -> ByondValueType {
-        self.internal.ByondValue_Type(v)
-    }
-    pub unsafe fn ByondValue_IsNull(&self, v: *const CByondValue) -> bool {
-        self.internal.ByondValue_IsNull(v)
-    }
-    pub unsafe fn ByondValue_IsNum(&self, v: *const CByondValue) -> bool {
-        self.internal.ByondValue_IsNum(v)
-    }
-    pub unsafe fn ByondValue_IsStr(&self, v: *const CByondValue) -> bool {
-        self.internal.ByondValue_IsStr(v)
-    }
-    pub unsafe fn ByondValue_IsList(&self, v: *const CByondValue) -> bool {
-        self.internal.ByondValue_IsList(v)
-    }
-    pub unsafe fn ByondValue_IsTrue(&self, v: *const CByondValue) -> bool {
-        self.internal.ByondValue_IsTrue(v)
-    }
-    pub unsafe fn ByondValue_GetNum(&self, v: *const CByondValue) -> f32 {
-        self.internal.ByondValue_GetNum(v)
-    }
-    pub unsafe fn ByondValue_GetRef(&self, v: *const CByondValue) -> u4c {
-        self.internal.ByondValue_GetRef(v)
-    }
-    pub unsafe fn ByondValue_SetNum(&self, v: *mut CByondValue, f: f32) {
-        self.internal.ByondValue_SetNum(v, f)
-    }
-    pub unsafe fn ByondValue_SetStr(&self, v: *mut CByondValue, str_: *const c_char) {
-        self.internal.ByondValue_SetStr(v, str_)
-    }
-    pub unsafe fn ByondValue_SetRef(&self, v: *mut CByondValue, type_: ByondValueType, ref_: u4c) {
-        self.internal.ByondValue_SetRef(v, type_, ref_)
-    }
-    pub unsafe fn ByondValue_Equals(&self, a: *const CByondValue, b: *const CByondValue) -> bool {
-        self.internal.ByondValue_Equals(a, b)
-    }
-    pub unsafe fn Byond_ThreadSync(
-        &self,
-        callback: ByondCallback,
-        data: *mut std::ffi::c_void,
-        block: bool,
-    ) -> CByondValue {
-        self.internal.Byond_ThreadSync(callback, data, block)
-    }
-    pub unsafe fn Byond_GetStrId(&self, str_: *const c_char) -> u4c {
-        self.internal.Byond_GetStrId(str_)
-    }
-    pub unsafe fn Byond_AddGetStrId(&self, str_: *const c_char) -> u4c {
-        self.internal.Byond_AddGetStrId(str_)
-    }
-    pub unsafe fn Byond_ReadVar(
-        &self,
-        loc: *const CByondValue,
-        varname: *const c_char,
-        result: *mut CByondValue,
-    ) -> bool {
-        self.internal.Byond_ReadVar(loc, varname, result)
-    }
-    pub unsafe fn Byond_ReadVarByStrId(
-        &self,
-        loc: *const CByondValue,
-        varname: u4c,
-        result: *mut CByondValue,
-    ) -> bool {
-        self.internal.Byond_ReadVarByStrId(loc, varname, result)
-    }
-    pub unsafe fn Byond_WriteVar(
-        &self,
-        loc: *const CByondValue,
-        varname: *const c_char,
-        val: *const CByondValue,
-    ) -> bool {
-        self.internal.Byond_WriteVar(loc, varname, val)
-    }
-    pub unsafe fn Byond_WriteVarByStrId(
-        &self,
-        loc: *const CByondValue,
-        varname: u4c,
-        val: *const CByondValue,
-    ) -> bool {
-        self.internal.Byond_WriteVarByStrId(loc, varname, val)
-    }
-    pub unsafe fn Byond_CreateList(&self, result: *mut CByondValue) -> bool {
-        self.internal.Byond_CreateList(result)
-    }
-    pub unsafe fn Byond_ReadList(
-        &self,
-        loc: *const CByondValue,
-        list: *mut CByondValue,
-        len: *mut u4c,
-    ) -> bool {
-        self.internal.Byond_ReadList(loc, list, len)
-    }
-    pub unsafe fn Byond_WriteList(
-        &self,
-        loc: *const CByondValue,
-        list: *const CByondValue,
-        len: u4c,
-    ) -> bool {
-        self.internal.Byond_WriteList(loc, list, len)
-    }
-    pub unsafe fn Byond_ReadListIndex(
-        &self,
-        loc: *const CByondValue,
-        idx: *const CByondValue,
-        result: *mut CByondValue,
-    ) -> bool {
-        self.internal.Byond_ReadListIndex(loc, idx, result)
-    }
-    pub unsafe fn Byond_WriteListIndex(
-        &self,
-        loc: *const CByondValue,
-        idx: *const CByondValue,
-        val: *const CByondValue,
-    ) -> bool {
-        self.internal.Byond_WriteListIndex(loc, idx, val)
-    }
-    pub unsafe fn Byond_ReadPointer(
-        &self,
-        ptr: *const CByondValue,
-        result: *mut CByondValue,
-    ) -> bool {
-        self.internal.Byond_ReadPointer(ptr, result)
-    }
-    pub unsafe fn Byond_WritePointer(
-        &self,
-        ptr: *const CByondValue,
-        val: *const CByondValue,
-    ) -> bool {
-        self.internal.Byond_WritePointer(ptr, val)
-    }
-    pub unsafe fn Byond_CallProc(
-        &self,
-        src: *const CByondValue,
-        name: *const c_char,
-        arg: *const CByondValue,
-        arg_count: u4c,
-        result: *mut CByondValue,
-    ) -> bool {
-        self.internal
-            .Byond_CallProc(src, name, arg, arg_count, result)
-    }
-    pub unsafe fn Byond_CallProcByStrId(
-        &self,
-        src: *const CByondValue,
-        name: u4c,
-        arg: *const CByondValue,
-        arg_count: u4c,
-        result: *mut CByondValue,
-    ) -> bool {
-        self.internal
-            .Byond_CallProcByStrId(src, name, arg, arg_count, result)
-    }
-    pub unsafe fn Byond_CallGlobalProc(
-        &self,
-        name: *const c_char,
-        arg: *const CByondValue,
-        arg_count: u4c,
-        result: *mut CByondValue,
-    ) -> bool {
-        self.internal
-            .Byond_CallGlobalProc(name, arg, arg_count, result)
-    }
-    pub unsafe fn Byond_CallGlobalProcByStrId(
-        &self,
-        name: u4c,
-        arg: *const CByondValue,
-        arg_count: u4c,
-        result: *mut CByondValue,
-    ) -> bool {
-        self.internal
-            .Byond_CallGlobalProcByStrId(name, arg, arg_count, result)
-    }
-    pub unsafe fn Byond_ToString(
-        &self,
-        src: *const CByondValue,
-        result: *mut c_char,
-        len: *mut u4c,
-    ) -> bool {
-        self.internal.Byond_ToString(src, result, len)
-    }
-    pub unsafe fn Byond_Block(
-        &self,
-        corner1: *const CByondXYZ,
-        corner2: *const CByondXYZ,
-        result: *mut CByondValue,
-        len: *mut u4c,
-    ) -> bool {
-        self.internal.Byond_Block(corner1, corner2, result, len)
-    }
-    pub unsafe fn Byond_Length(&self, src: *const CByondValue, result: *mut CByondValue) -> bool {
-        self.internal.Byond_Length(src, result)
-    }
-    pub unsafe fn Byond_LocateIn(
-        &self,
-        type_: *const CByondValue,
-        list: *const CByondValue,
-        result: *mut CByondValue,
-    ) -> bool {
-        self.internal.Byond_LocateIn(type_, list, result)
-    }
-    pub unsafe fn Byond_LocateXYZ(&self, xyz: *const CByondXYZ, result: *mut CByondValue) -> bool {
-        self.internal.Byond_LocateXYZ(xyz, result)
-    }
-    pub unsafe fn Byond_New(
-        &self,
-        type_: *const CByondValue,
-        argA: *const CByondValue,
-        argS: u4c,
-        result: *mut CByondValue,
-    ) -> bool {
-        self.internal.Byond_New(type_, argA, argS, result)
-    }
-    pub unsafe fn Byond_NewArglist(
-        &self,
-        type_: *const CByondValue,
-        arglist: *const CByondValue,
-        result: *mut CByondValue,
-    ) -> bool {
-        self.internal.Byond_NewArglist(type_, arglist, result)
-    }
-    pub unsafe fn Byond_Refcount(&self, type_: *const CByondValue, result: *mut u4c) -> bool {
-        self.internal.Byond_Refcount(type_, result)
-    }
-    pub unsafe fn Byond_XYZ(&self, src: *const CByondValue, xyz: *mut CByondXYZ) -> bool {
-        self.internal.Byond_XYZ(src, xyz)
-    }
-    pub unsafe fn ByondValue_IncRef(&self, src: *const CByondValue) {
-        self.internal.ByondValue_IncRef(src)
-    }
-    pub unsafe fn ByondValue_DecRef(&self, src: *const CByondValue) {
-        self.internal.ByondValue_DecRef(src)
-    }
-    pub unsafe fn Byond_TestRef(&self, src: *mut CByondValue) -> bool {
-        self.internal.Byond_TestRef(src)
-    }
-}