[librsvg: 5/9] Some more docs for c_api/handle

[Federico Mena Quintero <federico src gnome org>]

commit 9870e9b9326a1d84124526597fc5b050045a9a47
Author: Federico Mena Quintero <federico gnome org>
Date:   Wed May 26 19:15:05 2021 -0500

    Some more docs for c_api/handle

 src/c_api/handle.rs | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)
---
diff --git a/src/c_api/handle.rs b/src/c_api/handle.rs
index f269081f..38486f61 100644
--- a/src/c_api/handle.rs
+++ b/src/c_api/handle.rs
@@ -62,6 +62,8 @@ use super::messages::{rsvg_g_critical, rsvg_g_warning};
 use super::pixbuf_utils::{empty_pixbuf, pixbuf_from_surface};
 use super::sizing::LegacySize;
 
+// The C API exports global variables that contain the library's version number;
+// those get autogenerated from `build.rs` and placed in this `version.rs` file.
 include!(concat!(env!("OUT_DIR"), "/version.rs"));
 
 // This is basically the same as api::RenderingError but with extra cases for
@@ -88,6 +90,7 @@ impl fmt::Display for RenderingError {
     }
 }
 
+/// Rust version of the `RsvgHandleFlags` enum in C.
 #[glib::gflags("RsvgHandleFlags")]
 pub enum HandleFlags {
     #[gflags(name = "RSVG_HANDLE_FLAGS_NONE", nick = "flags-none")]
@@ -103,8 +106,10 @@ pub enum HandleFlags {
     KEEP_IMAGE_DATA = 1 << 1,
 }
 
+/// Type alias used to pass flags in the C API functions.
 pub type RsvgHandleFlags = u32;
 
+/// Internal representation of the loading flags, without bitflags.
 #[derive(Default, Copy, Clone)]
 struct LoadFlags {
     unlimited_size: bool,
@@ -162,16 +167,28 @@ pub struct RsvgHandle {
     _abi_padding: [glib_sys::gpointer; 16],
 }
 
+/// State machine for `RsvgHandle`.
+///
+/// When an `RsvgHandled` is created it is empty / not loaded yet, and it does not know
+/// whether the caller will feed it data gradually with the legacy `write()/close()` API,
+/// or whether it will be given a `GInputStream` to read in a blocking fashion.  After the
+/// handle is loaded (e.g. the SVG document is finished parsing), we make sure that no
+/// further loading operations can be done.
 #[allow(clippy::large_enum_variant)]
 enum LoadState {
-    // Just created the CHandle
+    /// Just created the CHandle; nothing loaded yet.
     Start,
 
-    // Being loaded using the legacy write()/close() API
+    /// Being loaded using the legacy write()/close() API.
+    ///
+    /// We buffer all the data from `write()` calls until the time `close()` is called;
+    /// then we run the buffer through a decompressor in case this is an SVGZ file.
     Loading { buffer: Vec<u8> },
 
+    /// Loading finished successfully; the document is in the `SvgHandle`.
     ClosedOk { handle: SvgHandle },
 
+    /// Loaded unsuccessfully.
     ClosedError,
 }
 
@@ -197,7 +214,7 @@ impl LoadState {
 /// Holds the base URL for loading a handle, and the C-accessible version of it
 ///
 /// There is a public API to query the base URL, and we need to
-/// produce a CString with it.  However, that API returns a
+/// produce a CString with it.  However, that API returns a borrowed
 /// *const char, so we need to maintain a long-lived CString along with the
 /// internal Url.
 #[derive(Default)]