fontique: Improve docs

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).
+    /// 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).
+    /// 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)
     }
@@ -130,6 +152,11 @@ impl Collection {
 
     /// Returns an iterator over the fallback families for the given
     /// key.
+    ///
+    /// # See also
+    ///
+    /// * [`Collection::append_fallbacks()`]
+    /// * [`Collection::set_fallbacks()`]
     pub fn fallback_families(
         &mut self,
         key: impl Into<FallbackKey>,
@@ -139,6 +166,11 @@ impl Collection {
 
     /// Replaces the set of family identifiers associated with the fallback
     /// key.
+    ///
+    /// # See also
+    ///
+    /// * [`Collection::append_fallbacks()`]
+    /// * [`Collection::fallback_families()`]
     pub fn set_fallbacks(
         &mut self,
         key: impl Into<FallbackKey>,
@@ -148,6 +180,11 @@ impl Collection {
     }
 
     /// Appends the set of family identifiers to the given fallback key.
+    ///
+    /// # See also
+    ///
+    /// * [`Collection::fallback_families()`]
+    /// * [`Collection::set_fallbacks()`]
     pub fn append_fallbacks(
         &mut self,
         key: impl Into<FallbackKey>,

fontique/src/collection/query.rs

@@ -28,6 +28,8 @@ impl QueryState {
 }
 
 /// State for font selection.
+///
+/// Instances of this can be obtained from [`Collection::query()`].
 pub struct Query<'a> {
     collection: &'a mut Inner,
     state: &'a mut QueryState,
@@ -103,6 +105,9 @@ impl<'a> Query<'a> {
 
     /// Invokes the given callback with all fonts that match the current
     /// settings.
+    ///
+    /// Return [`QueryStatus::Stop`] to end iterating over the matching
+    /// fonts or [`QueryStatus::Continue`] to continue iterating.
     #[cfg(feature = "std")]
     pub fn matches_with(&mut self, mut f: impl FnMut(&QueryFont) -> QueryStatus) {
         for family in self

fontique/src/fallback.rs

@@ -36,7 +36,7 @@ impl FallbackMap {
     /// Inserts or replaces the fallback families for the given script and
     /// language.
     ///
-    /// Returns false if we don't track that particular pair of script and
+    /// Returns `false` if we don't track that particular pair of script and
     /// language.
     pub fn set(
         &mut self,
@@ -49,7 +49,7 @@ impl FallbackMap {
     /// Inserts or appends the fallback families for the given script and
     /// language.
     ///
-    /// Returns false if we don't track that particular pair of script and
+    /// Returns `false` if we don't track that particular pair of script and
     /// language.
     pub fn append(
         &mut self,
@@ -105,6 +105,12 @@ impl FallbackMap {
 }
 
 /// Describes a selector for fallback families.
+///
+/// This is a [`Script`] and optionally, a `locale`, represented
+/// as a `&'static str`.
+///
+/// It can be constructed directly via [`FallbackKey::new()`] or any of
+/// a variety of `From` implementations to improve the ease of use.
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 pub struct FallbackKey {
     script: Script,
@@ -139,15 +145,15 @@ impl FallbackKey {
         self.locale
     }
 
-    /// Returns true if the requested locale is considered the "default"
+    /// Returns `true` if the requested locale is considered the "default"
     /// language/region for the requested script.
     ///
     /// Always returns `true` when `locale()` returns `None`.
     pub fn is_default(&self) -> bool {
         self.is_default
     }
 
-    /// Returns true if the requested script and locale pair are actually
+    /// Returns `true` if the requested script and locale pair are actually
     /// tracked for fallback.
     pub fn is_tracked(&self) -> bool {
         self.is_tracked