[librsvg: 6/7] Toplevel module docs for c_api




commit 4fb3a89f73713a5d4818ba6849cf2780f344cc47
Author: Federico Mena Quintero <federico gnome org>
Date:   Wed Oct 28 12:44:11 2020 -0600

    Toplevel module docs for c_api

 librsvg/c_api.rs | 38 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)
---
diff --git a/librsvg/c_api.rs b/librsvg/c_api.rs
index 239dea5f..84de9796 100644
--- a/librsvg/c_api.rs
+++ b/librsvg/c_api.rs
@@ -1,3 +1,27 @@
+//! Rust implementation of the C API for librsvg.
+//!
+//! The C API of librsvg revolves around an `RsvgHandle` GObject class, which is
+//! implemented as follows:
+//!
+//! * [`RsvgHandle`] and [`RsvgHandleClass`] are derivatives of `GObject` and
+//! `GObjectClass`.  These are coded explicitly, instead of using
+//! `glib::subclass::simple::InstanceStruct<T>` and
+//! `glib::subclass::simple::ClassStruct<T>`, as the structs need need to be kept
+//! ABI-compatible with the traditional C API/ABI.
+//!
+//! * The actual data for a handle (e.g. the `RsvgHandle`'s private data, in GObject
+//! parlance) is in [`CHandle`].
+//!
+//! * Public C ABI functions are the `#[no_mangle]` functions with an `rsvg_` prefix.
+//!
+//! The C API is implemented in terms of the Rust API in `librsvg_crate`.  In effect,
+//! `RsvgHandle` is a rather convoluted builder or adapter pattern that translates all the
+//! historical idiosyncrasies of the C API into the simple Rust API.
+//!
+//! [`RsvgHandle`]: struct.RsvgHandle.html
+//! [`RsvgHandleClass`]: struct.RsvgHandleClass.html
+//! [`CHandle`]: struct.CHandle.html
+
 use std::cell::{Cell, Ref, RefCell, RefMut};
 use std::ffi::{CStr, CString};
 use std::ops;
@@ -133,17 +157,27 @@ impl From<LoadFlags> for HandleFlags {
     }
 }
 
-// Keep this in sync with rsvg.h:RsvgHandleClass
+/// GObject class struct for RsvgHandle.
+///
+/// This is not done through `glib::subclass::simple::ClassStruct<T>` because we need
+/// to include the `_abi_padding` field for ABI compatibility with the C headers, and
+/// `simple::ClassStruct` does not allow that.
 #[repr(C)]
 pub struct RsvgHandleClass {
+    // Keep this in sync with rsvg.h:RsvgHandleClass
     parent: gobject_sys::GObjectClass,
 
     _abi_padding: [glib_sys::gpointer; 15],
 }
 
-// Keep this in sync with rsvg.h:RsvgHandle
+/// GObject instance struct for RsvgHandle.
+///
+/// This is not done through `glib::subclass::simple::InstanceStruct<T>` because we need
+/// to include the `_abi_padding` field for ABI compatibility with the C headers, and
+/// `simple::InstanceStruct` does not allow that.
 #[repr(C)]
 pub struct RsvgHandle {
+    // Keep this in sync with rsvg.h:RsvgHandle
     parent: gobject_sys::GObject,
 
     _abi_padding: [glib_sys::gpointer; 16],


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]