fontique: Improve docs

Author: waywardmonkeys

fontique/Cargo.toml

@@ -9,6 +9,9 @@ rust-version.workspace = true
 license.workspace = true
 repository.workspace = true
 
+[package.metadata.docs.rs]
+all-features = true
+
 [lints]
 workspace = true
 

fontique/src/attributes.rs

@@ -8,7 +8,7 @@ use core_maths::*;
 
 use core::fmt;
 
-/// Primary attributes for font matching: stretch, style and weight.
+/// Primary attributes for font matching: [`Stretch`], [`Style`] and [`Weight`].
 #[derive(Copy, Clone, PartialEq, Default, Debug)]
 pub struct Attributes {
     pub stretch: Stretch,
@@ -38,7 +38,9 @@ impl fmt::Display for Attributes {
 }
 
 /// Visual width of a font-- a relative change from the normal aspect
-/// ratio, typically in the range 0.5 to 2.0.
+/// ratio, typically in the range `0.5` to `2.0`.
+///
+/// The default value is [`Stretch::NORMAL`] or `1.0`.
 ///
 /// In variable fonts, this can be controlled with the `wdth` axis.
 ///
@@ -59,7 +61,7 @@ impl Stretch {
     /// Width that is 87.5% of normal.
     pub const SEMI_CONDENSED: Self = Self(0.875);
 
-    /// Width that is 100% of normal.
+    /// Width that is 100% of normal. This is the default value.
     pub const NORMAL: Self = Self(1.0);
 
     /// Width that is 112.5% of normal.
@@ -77,45 +79,112 @@ impl Stretch {
 
 impl Stretch {
     /// Creates a new stretch attribute with the given ratio.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use fontique::Stretch;
+    /// assert_eq!(Stretch::from_ratio(1.5), Stretch::EXTRA_EXPANDED);
+    /// ```
+    ///
+    /// # See also
+    ///
+    /// * [`Stretch::from_percentage()`]
+    /// * [`Stretch::ratio()`]
     pub fn from_ratio(ratio: f32) -> Self {
         Self(ratio)
     }
 
     /// Creates a stretch attribute from a percentage.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use fontique::Stretch;
+    /// assert_eq!(Stretch::from_percentage(87.5), Stretch::SEMI_CONDENSED);
+    /// ```
+    ///
+    /// # See also
+    ///
+    /// * [`Stretch::from_ratio()`]
+    /// * [`Stretch::percentage()`]
     pub fn from_percentage(percentage: f32) -> Self {
         Self(percentage / 100.0)
     }
 
     /// Returns the stretch attribute as a ratio.
     ///
-    /// This is a linear scaling factor with 1.0 being "normal" width.
+    /// This is a linear scaling factor with `1.0` being "normal" width.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use fontique::Stretch;
+    /// assert_eq!(Stretch::NORMAL.ratio(), 1.0);
+    /// ```
+    ///
+    /// # See also
+    ///
+    /// * [`Stretch::from_ratio()`]
+    /// * [`Stretch::percentage()`]
     pub fn ratio(self) -> f32 {
         self.0
     }
 
     /// Returns the stretch attribute as a percentage value.
     ///
     /// This is generally the value associated with the `wdth` axis.
+    ///
+    /// # See also
+    ///
+    /// * [`Stretch::from_percentage()`]
+    /// * [`Stretch::ratio()`]
     pub fn percentage(self) -> f32 {
         self.0 * 100.0
     }
 
-    /// Returns true if the stretch is normal.
+    /// Returns true if the stretch is [normal].
+    ///
+    /// # See also
+    ///
+    /// * [`Stretch::is_condensed()`]
+    /// * [`Stretch::is_expanded()`]
+    ///
+    /// [normal]: Stretch::NORMAL
     pub fn is_normal(self) -> bool {
         self == Self::NORMAL
     }
 
     /// Returns true if the stretch is condensed (less than normal).
+    ///
+    /// # See also
+    ///
+    /// * [`Stretch::is_expanded()`]
+    /// * [`Stretch::is_normal()`]
     pub fn is_condensed(self) -> bool {
         self < Self::NORMAL
     }
 
     /// Returns true if the stretch is expanded (greater than normal).
+    ///
+    /// # See also
+    ///
+    /// * [`Stretch::is_condensed()`]
+    /// * [`Stretch::is_normal()`]
     pub fn is_expanded(self) -> bool {
         self > Self::NORMAL
     }
 
     /// Parses the stretch from a CSS style keyword or a percentage value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use fontique::Stretch;
+    /// assert_eq!(Stretch::parse("semi-condensed"), Some(Stretch::SEMI_CONDENSED));
+    /// assert_eq!(Stretch::parse("80%"), Some(Stretch::from_percentage(80.0)));
+    /// assert_eq!(Stretch::parse("wideload"), None);
+    /// ```
     pub fn parse(s: &str) -> Option<Self> {
         let s = s.trim();
         Some(match s {
@@ -171,6 +240,8 @@ impl Default for Stretch {
 
 /// Visual weight class of a font, typically on a scale from 1.0 to 1000.0.
 ///
+/// The default value is [`Weight::NORMAL`] or `400.0`.
+///
 /// In variable fonts, this can be controlled with the `wght` axis.
 ///
 /// See <https://fonts.google.com/knowledge/glossary/weight>
@@ -190,7 +261,7 @@ impl Weight {
     /// Weight value of 350.
     pub const SEMI_LIGHT: Self = Self(350.0);
 
-    /// Weight value of 400.
+    /// Weight value of 400. This is the default value.
     pub const NORMAL: Self = Self(400.0);
 
     /// Weight value of 500.
@@ -224,6 +295,16 @@ impl Weight {
     }
 
     /// Parses a CSS style font weight attribute.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use fontique::Weight;
+    /// assert_eq!(Weight::parse("normal"), Some(Weight::NORMAL));
+    /// assert_eq!(Weight::parse("bold"), Some(Weight::BOLD));
+    /// assert_eq!(Weight::parse("850"), Some(Weight::new(850.0)));
+    /// assert_eq!(Weight::parse("invalid"), None);
+    /// ```
     pub fn parse(s: &str) -> Option<Self> {
         let s = s.trim();
         Some(match s {
@@ -265,6 +346,8 @@ impl fmt::Display for Weight {
 
 /// Visual style or 'slope' of a font.
 ///
+/// The default value is [`Style::Normal`].
+///
 /// In variable fonts, this can be controlled with the `ital`
 /// and `slnt` axes for italic and oblique styles, respectively.
 ///

fontique/src/collection/mod.rs

@@ -28,7 +28,7 @@ use std::sync::{atomic::Ordering, Mutex};
 
 type FamilyMap = HashMap<FamilyId, Option<FamilyInfo>>;
 
-/// Options for a font collection.
+/// Options for a [font collection](Collection).
 #[derive(Copy, Clone, Debug)]
 pub struct CollectionOptions {
     /// If true, the font collection will use a secondary shared store
@@ -38,13 +38,13 @@ pub struct CollectionOptions {
     /// If the font collection will be used by a single thread, this is
     /// pure overhead and should be disabled.
     ///
-    /// The default value is false.
+    /// The default value is `false`.
     pub shared: bool,
 
     /// If true, the font collection will provide access to system fonts
     /// using platform specific APIs.
     ///
-    /// The default value is true.
+    /// The default value is `true`.
     pub system_fonts: bool,
 }
 
@@ -66,6 +66,14 @@ pub struct Collection {
 
 impl Collection {
     /// Creates a new collection with the given options.
+    ///
+    /// If `fontique` was compiled with the `"system"` feature and
+    /// [`CollectionOptions::system_fonts`] was set to `true` when
+    /// creating this collection, then it will register the fonts
+    /// available on the system.
+    ///
+    /// Additional fonts can be registered via [`Collection::register_fonts()`]
+    /// and providing it with the data for those fonts.
     pub fn new(options: CollectionOptions) -> Self {
         Self {
             inner: Inner::new(options),
@@ -75,12 +83,18 @@ impl Collection {
 
     /// Returns an iterator over all available family names in the collection.
     ///
-    /// This includes both system and registered fonts.
+    /// If `fontique` was compiled with the `"system"` feature, then it will
+    /// include system fonts after the registered fonts.
     pub fn family_names(&mut self) -> impl Iterator<Item = &str> + '_ + Clone {
         self.inner.family_names()
     }
 
     /// Returns the family identifier for the given family name.
+    ///
+    /// # See also
+    ///
+    /// * [`Collection::family_name()`]
+    /// * [`Collection::family_names()`]
     pub fn family_id(&mut self, name: &str) -> Option<FamilyId> {
         self.inner.family_id(name)
     }
@@ -91,11 +105,19 @@ impl Collection {
     }
 
     /// Returns the family object for the given family identifier.
+    ///
+    /// # See also
+    ///
+    /// * [`Collection::family_by_name()`]
     pub fn family(&mut self, id: FamilyId) -> Option<FamilyInfo> {
         self.inner.family(id)
     }
 
     /// Returns the family object for the given name.
+    ///
+    /// # See also
+    ///
+    /// * [`Collection::family()`]
     pub fn family_by_name(&mut self, name: &str) -> Option<FamilyInfo> {
         self.inner.family_by_name(name)
     }

fontique/src/font.rs

@@ -67,7 +67,7 @@ impl FontInfo {
     }
 
     /// Returns the visual width of the font-- a relative change from the normal
-    /// aspect ratio, typically in the range 0.5 to 2.0.
+    /// aspect ratio, typically in the range `0.5` to `2.0`.
     pub fn stretch(&self) -> Stretch {
         self.stretch
     }
@@ -78,7 +78,7 @@ impl FontInfo {
     }
 
     /// Returns the visual weight class of the font, typically on a scale
-    /// from 1.0 to 1000.0.
+    /// from `1.0` to `1000.0`.
     pub fn weight(&self) -> Weight {
         self.weight
     }
@@ -230,6 +230,17 @@ const ITALIC_AXIS: u8 = 0x08;
 const OPTICAL_SIZE_AXIS: u8 = 0x10;
 
 /// An axis of variation for a variable font.
+///
+/// Instances of this can be obtained from [`FontInfo::axes()`].
+///
+/// # See also
+///
+/// * [`FontInfo::axes()`]
+/// * [`FontInfo::has_italic_axis()`]
+/// * [`FontInfo::has_optical_size_axis()`]
+/// * [`FontInfo::has_slant_axis()`]
+/// * [`FontInfo::has_weight_axis()`]
+/// * [`FontInfo::has_width_axis()`]
 #[derive(Copy, Clone, Default, Debug)]
 pub struct AxisInfo {
     /// The tag that identifies the axis.

fontique/src/generic.rs

@@ -14,7 +14,7 @@ type FamilyVec = SmallVec<[FamilyId; 2]>;
 #[repr(u8)]
 pub enum GenericFamily {
     /// Glyphs have finishing strokes, flared or tapering ends, or have actual
-    ///  serifed endings.
+    /// serifed endings.
     Serif = 0,
     /// Glyphs have stroke endings that are plain.
     SansSerif = 1,

fontique/src/lib.rs

@@ -3,6 +3,7 @@
 
 //! Font enumeration and fallback.
 
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 // TODO: Remove this dead code allowance and hide the offending code behind the std feature gate.
 #![cfg_attr(not(feature = "std"), allow(dead_code))]
 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]

fontique/src/source_cache.rs

@@ -20,7 +20,7 @@ pub struct SourceCacheOptions {
     /// This is useful for ensuring that only one copy of font data is
     /// loaded into memory in multi-threaded scenarios.
     ///
-    /// The default value is false.
+    /// The default value is `false`.
     pub shared: bool,
 }