Add docs and safety comments

Author: CraftSpider

crates/mac_core/Cargo.toml

@@ -1,3 +1,5 @@
+lints.workspace = true
+
 [package]
 name = "tectonic_mac_core"
 license = "MIT"

crates/mac_core/build.rs

@@ -1,3 +1,5 @@
+//! Mac core library build script. Links to framework libraries when targeting MacOS.
+
 use tectonic_cfg_support::target_cfg;
 
 fn main() {

crates/mac_core/src/array.rs

@@ -5,11 +5,14 @@ use std::ptr;
 use std::ptr::NonNull;
 
 cfty! {
+    /// A homogeneous array of CFType values, similar to [`Vec`].
     CFArray<T> : CFArrayGetTypeID
 }
 
 impl<T: CoreType> CFArray<T> {
+    /// Create a new, empty [`CFArray`].
     pub fn empty() -> CFArray<T> {
+        // SAFETY: Valid to call with all null and zero length + default callbacks
         let ptr = unsafe {
             sys::CFArrayCreate(
                 ptr::null_mut(),
@@ -18,10 +21,15 @@ impl<T: CoreType> CFArray<T> {
                 &sys::kCFTypeArrayCallBacks,
             )
         };
-        CFArray::new_owned(NonNull::new(ptr.cast_mut()).unwrap())
+        let ptr = NonNull::new(ptr.cast_mut()).unwrap();
+        // SAFETY: If non-null, pointer from CFArrayCreate is a new, owned CFArray.
+        unsafe { CFArray::new_owned(ptr) }
     }
 
+    /// Create a new [`CFArray`] that contains the provided values.
     pub fn new(values: &[T]) -> CFArray<T> {
+        // SAFETY: Length matches provided slice and values are `CoreType` so must be valid
+        //         CFTypeRefs.
         let ptr = unsafe {
             sys::CFArrayCreate(
                 ptr::null_mut(),
@@ -30,13 +38,18 @@ impl<T: CoreType> CFArray<T> {
                 &sys::kCFTypeArrayCallBacks,
             )
         };
-        CFArray::new_owned(NonNull::new(ptr.cast_mut()).unwrap())
+        let ptr = NonNull::new(ptr.cast_mut()).unwrap();
+        // SAFETY: If non-null, pointer from CFCArrayCreate is a new, owned CFArray.
+        unsafe { CFArray::new_owned(ptr) }
     }
 
+    /// Get the length of this array
     pub fn len(&self) -> usize {
+        // SAFETY: Internal pointer is guaranteed valid.
         unsafe { sys::CFArrayGetCount(self.0.as_ptr()) as usize }
     }
 
+    /// Check whether this array is empty
     pub fn is_empty(&self) -> bool {
         self.len() == 0
     }
@@ -46,12 +59,14 @@ impl<T: CoreType> Index<usize> for CFArray<T> {
     type Output = T;
 
     fn index(&self, index: usize) -> &Self::Output {
+        if index >= self.len() {
+            panic!("Index {index} out of bounds for CFArray");
+        }
+        // SAFETY: Internal pointer is guaranteed valid. Index has been verified in-bounds.
         let ptr =
             unsafe { sys::CFArrayGetValueAtIndex(self.0.cast().as_ptr(), index as sys::CFIndex) }
                 .cast::<T>();
-        if ptr.is_null() {
-            panic!("Index {index} out of bounds for CFArray");
-        }
+        // SAFETY: API contracts ensure all values are of the correct type and live for our lifetime.
         unsafe { &*ptr }
     }
 }

crates/mac_core/src/dict.rs

@@ -42,14 +42,15 @@ impl<K, V, const N: usize> Pairs for [(K, V); N] {
     type Values = [V; N];
 
     fn into_pairs(self) -> (Self::Keys, Self::Values) {
-        let mut keys: [MaybeUninit<K>; N] = unsafe { MaybeUninit::uninit().assume_init() };
-        let mut values: [MaybeUninit<V>; N] = unsafe { MaybeUninit::uninit().assume_init() };
+        let mut keys: [MaybeUninit<K>; N] = [const { MaybeUninit::uninit() }; N];
+        let mut values: [MaybeUninit<V>; N] = [const { MaybeUninit::uninit() }; N];
 
         for (idx, (key, val)) in self.into_iter().enumerate() {
             keys[idx].write(key);
             values[idx].write(val);
         }
 
+        // SAFETY: All values in both arrays have been initialized
         unsafe {
             (
                 mem::transmute_copy::<_, [K; N]>(&keys),
@@ -69,13 +70,17 @@ impl<K, V> Pairs for Vec<(K, V)> {
 }
 
 cfty! {
+    /// A dictionary / map of CFType keys to values, similar to [`HashMap`](std::collections::HashMap)
     CFDictionary<K, V> : CFDictionaryGetTypeID
 }
 
 impl<K: CoreType, V: CoreType> CFDictionary<K, V> {
+    /// Create a new [`CFDictionary`] that contains the provided key/value pairs.
     pub fn new<P: Pairs>(pairs: P) -> CFDictionary<K, V> {
         let (keys, values) = pairs.into_pairs();
 
+        // SAFETY: Length matches provided slices and values are `CoreType` so must be valid
+        //         CFTypeRefs.
         let ptr = unsafe {
             sys::CFDictionaryCreate(
                 ptr::null_mut(),
@@ -86,6 +91,8 @@ impl<K: CoreType, V: CoreType> CFDictionary<K, V> {
                 &sys::kCFTypeDictionaryValueCallBacks,
             )
         };
-        CFDictionary::new_owned(NonNull::new(ptr.cast_mut()).unwrap())
+        let ptr = NonNull::new(ptr.cast_mut()).unwrap();
+        // SAFETY: If non-null, pointer from CFDictionaryCreate is a new, owned CFDictionary.
+        unsafe { CFDictionary::new_owned(ptr) }
     }
 }

crates/mac_core/src/font.rs

@@ -2,84 +2,127 @@ use super::{sys, CFString, CFType, CTFontDescriptor, CoreType};
 use std::ptr;
 use std::ptr::NonNull;
 
+/// An attribute that may be found in a font, such as family name or URL.
 #[derive(Copy, Clone)]
 pub enum FontAttribute {
+    /// Name
     Name,
+    /// Family Name
     FamilyName,
+    /// Display Name
     DisplayName,
+    /// URL
     URL,
+    /// Cascade List - fallbacks to use if glyph not present in this font.
     CascadeList,
 }
 
 impl FontAttribute {
+    /// Convert this attribute into its matching [`CFString`].
     pub fn to_str(self) -> CFString {
-        CFString::new_borrowed(NonNull::new(self.to_raw().cast_mut()).unwrap())
+        let ptr = NonNull::new(self.to_raw().cast_mut()).unwrap();
+        // SAFETY: The value returned by `to_raw` is guaranteed to be a valid CFStringRef
+        unsafe { CFString::new_borrowed(ptr) }
     }
 
+    /// Convert this attribute into a raw pointer to a [`CFString`].
     pub fn to_raw(self) -> sys::CFStringRef {
         match self {
+            // SAFETY: Static guaranteed to exist and by a valid CFStringRef
             FontAttribute::Name => unsafe { sys::kCTFontNameAttribute },
+            // SAFETY: sic
             FontAttribute::FamilyName => unsafe { sys::kCTFontFamilyNameAttribute },
+            // SAFETY: sic
             FontAttribute::DisplayName => unsafe { sys::kCTFontDisplayNameAttribute },
+            // SAFETY: sic
             FontAttribute::URL => unsafe { sys::kCTFontURLAttribute },
+            // SAFETY: sic
             FontAttribute::CascadeList => unsafe { sys::kCTFontCascadeListAttribute },
         }
     }
 }
 
+/// A type of font name that may be available.
 #[derive(Copy, Clone)]
 pub enum FontNameKey {
+    /// Full name
     Full,
+    /// Family name
     Family,
+    /// Style name
     Style,
+    /// PostScript name
     PostScript,
 }
 
 impl FontNameKey {
+    /// Convert this attribute into its matching [`CFString`].
     pub fn to_str(self) -> CFString {
-        CFString::new_borrowed(NonNull::new(self.to_raw().cast_mut()).unwrap())
+        let ptr = NonNull::new(self.to_raw().cast_mut()).unwrap();
+        // SAFETY: The value returned by `to_raw` is guaranteed to be a valid CFStringRef
+        unsafe { CFString::new_borrowed(ptr) }
     }
 
     fn to_raw(self) -> sys::CFStringRef {
         match self {
+            // SAFETY: Static guaranteed to exist and by a valid CFStringRef
             FontNameKey::Full => unsafe { sys::kCTFontFullNameKey },
+            // SAFETY: sic
             FontNameKey::Family => unsafe { sys::kCTFontFamilyNameKey },
+            // SAFETY: sic
             FontNameKey::Style => unsafe { sys::kCTFontStyleNameKey },
+            // SAFETY: sic
             FontNameKey::PostScript => unsafe { sys::kCTFontPostScriptNameKey },
         }
     }
 }
 
 cfty! {
+    /// A font, combining a descriptor and a size, as well as any other necessary transforms to
+    /// render glyphs.
     CTFont : CTFontGetTypeID
 }
 
 impl CTFont {
+    /// Create a new font from a [`CTFontDescriptor`] and a size to render at.
     pub fn new_descriptor(descriptor: &CTFontDescriptor, size: f64) -> CTFont {
+        // SAFETY: Provided descriptor is guaranteed valid. Any size will work. Null matrix is always
+        //         allowed.
         let ptr = unsafe {
             sys::CTFontCreateWithFontDescriptor(
                 descriptor.as_type_ref(),
                 size as sys::CGFloat,
                 ptr::null_mut(),
             )
         };
-        CTFont::new_owned(NonNull::new(ptr.cast_mut()).unwrap())
+        let ptr = NonNull::new(ptr.cast_mut()).unwrap();
+        // SAFETY: If non-null, pointer from CTFontCreateWithFontDescriptor is a new, owned CTFont.
+        unsafe { CTFont::new_owned(ptr) }
     }
 
+    /// Get an attribute of this font, if present
     pub fn attr(&self, attr: FontAttribute) -> Option<CFType> {
+        // SAFETY: Internal pointer and attribute string guaranteed valid.
         let ptr = unsafe { sys::CTFontCopyAttribute(self.as_type_ref(), attr.to_raw()) };
-        NonNull::new(ptr.cast_mut()).map(CFType::new_owned)
+        // SAFETY: In non-null, returned name guaranteed valid and owned.
+        NonNull::new(ptr.cast_mut()).map(|ptr| unsafe { CFType::new_owned(ptr) })
     }
 
+    /// Get a name value of this font, if present
     pub fn name(&self, name: FontNameKey) -> Option<CFString> {
+        // SAFETY: Internal pointer and name string guaranteed valid.
         let ptr = unsafe { sys::CTFontCopyName(self.as_type_ref(), name.to_raw()) };
-        NonNull::new(ptr.cast_mut()).map(CFString::new_owned)
+        // SAFETY: In non-null, returned name guaranteed valid and owned.
+        NonNull::new(ptr.cast_mut()).map(|ptr| unsafe { CFString::new_owned(ptr) })
     }
 
+    /// Get the name of this font, localized to a specific language
     pub fn localized_name(&self, name: FontNameKey) -> Option<CFString> {
+        // SAFETY: Internal pointer and name string guaranteed valid.
         let ptr = unsafe {
             sys::CTFontCopyLocalizedName(self.as_type_ref(), name.to_raw(), ptr::null_mut())
         };
-        NonNull::new(ptr.cast_mut()).map(CFString::new_owned)
+        // SAFETY: In non-null, returned name guaranteed valid and owned.
+        NonNull::new(ptr.cast_mut()).map(|ptr| unsafe { CFString::new_owned(ptr) })
     }
 }

crates/mac_core/src/font_desc.rs

@@ -2,39 +2,58 @@ use super::{sys, CFArray, CFDictionary, CFSet, CFString, CFType, CoreType, FontA
 use std::ptr::NonNull;
 
 cfty! {
+    /// A font descriptor, a typeface that can be paired with a size and transform to get a specific
+    /// font.
     CTFontDescriptor : CTFontDescriptorGetTypeID
 }
 
 impl CTFontDescriptor {
+    /// Create a new descriptor from a dictionary of its attributes. Unrecognized attributes will
+    /// be ignored.
     pub fn new_with_attrs(attrs: &CFDictionary<CFString, CFType>) -> CTFontDescriptor {
+        // SAFETY: Attrs is guaranteed to be valid
         let ptr = unsafe { sys::CTFontDescriptorCreateWithAttributes(attrs.as_type_ref()) };
-        CTFontDescriptor::new_owned(NonNull::new(ptr.cast_mut()).unwrap())
+        let ptr = NonNull::new(ptr.cast_mut()).unwrap();
+        // SAFETY: If non-null, pointer from CTFontDescriptorCreateWithAttributes is a new, owned CTFontDescriptor.
+        unsafe { CTFontDescriptor::new_owned(ptr) }
     }
 
+    /// Create a copy of this descriptor, but with additional attributes as specified by `attrs`.
+    /// Overlapping attributes are replaced.
     pub fn copy_with_attrs(&self, attrs: &CFDictionary<CFString, CFType>) -> CTFontDescriptor {
+        // SAFETY: Self and attrs are guaranteed to be valid
         let ptr = unsafe {
             sys::CTFontDescriptorCreateCopyWithAttributes(self.as_type_ref(), attrs.as_type_ref())
         };
-        CTFontDescriptor::new_owned(NonNull::new(ptr.cast_mut()).unwrap())
+        let ptr = NonNull::new(ptr.cast_mut()).unwrap();
+        // SAFETY: If non-null, pointer from CTFontDescriptorCreateCopyWithAttributes is a new, owned CTFontDescriptor.
+        unsafe { CTFontDescriptor::new_owned(ptr) }
     }
 
+    /// Find all loaded fonts that contain the provided mandatory properties.
     pub fn matching_font_descriptors(
         &self,
         mandatory: &CFSet<CFString>,
     ) -> CFArray<CTFontDescriptor> {
+        // SAFETY: Self and mandatory are guaranteed to be valid
         let ptr = unsafe {
             sys::CTFontDescriptorCreateMatchingFontDescriptors(
                 self.as_type_ref(),
                 mandatory.as_type_ref(),
             )
         };
         NonNull::new(ptr.cast_mut())
-            .map(CFArray::new_owned)
+            // SAFETY: If non-null, pointer from CTFontDescriptorCreateMatchingFontDescriptors is a
+            //         new, owned CFArray of CTFontDescriptor
+            .map(|ptr| unsafe { CFArray::new_owned(ptr) })
             .unwrap_or_else(CFArray::empty)
     }
 
+    /// Get an attribute of this font descriptor, if present.
     pub fn attr(&self, attr: FontAttribute) -> Option<CFType> {
+        // SAFETY: Self and attr are guaranteed to be valid
         let ptr = unsafe { sys::CTFontDescriptorCopyAttribute(self.as_type_ref(), attr.to_raw()) };
-        NonNull::new(ptr.cast_mut()).map(CFType::new_owned)
+        // SAFETY: If non-null, pointer from CTFontDescriptorCreateMatchingFontDescriptors is a new, owned CFType instance
+        NonNull::new(ptr.cast_mut()).map(|ptr| unsafe { CFType::new_owned(ptr) })
     }
 }