fontique: Improve docs (#97)

.clippy.toml

@@ -3,3 +3,5 @@
 # it makes sense to optimize for 64-bit and accept the performance hits on 32-bit.
 # 16 bytes is the number of bytes that fits into two 64-bit CPU registers.
 trivial-copy-size-limit = 16
+# Don't warn about these identifiers when using clippy::doc_markdown.
+doc-valid-idents = ["OpenType", ".."]

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,12 @@ use core_maths::*;
 
 use core::fmt;
 
-/// Primary attributes for font matching: stretch, style and weight.
+/// Primary attributes for font matching: [`Stretch`], [`Style`] and [`Weight`].
+///
+/// These are used to [configure] a [`Query`].
+///
+/// [configure]: crate::Query::set_attributes
+/// [`Query`]: crate::Query
 #[derive(Copy, Clone, PartialEq, Default, Debug)]
 pub struct Attributes {
     pub stretch: Stretch,
@@ -38,11 +43,18 @@ 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`.
 ///
-/// In variable fonts, this can be controlled with the `wdth` axis.
+/// The default value is [`Stretch::NORMAL`] or `1.0`.
+///
+/// In variable fonts, this can be controlled with the `wdth` [axis].
 ///
 /// See <https://fonts.google.com/knowledge/glossary/width>
+///
+/// In CSS, this corresponds to the [`font-width`] property.
+///
+/// [axis]: crate::AxisInfo
+/// [`font-width`]: https://www.w3.org/TR/css-fonts-4/#font-width-prop
 #[derive(Copy, Clone, PartialEq, PartialOrd, Debug)]
 pub struct Stretch(f32);
 
@@ -59,7 +71,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,18 +89,43 @@ impl Stretch {
 
 impl Stretch {
     /// Creates a new stretch attribute with the given ratio.
+    ///
+    /// This can also be created [from a percentage](Self::from_percentage).
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use fontique::Stretch;
+    /// assert_eq!(Stretch::from_ratio(1.5), Stretch::EXTRA_EXPANDED);
+    /// ```
     pub fn from_ratio(ratio: f32) -> Self {
         Self(ratio)
     }
 
     /// Creates a stretch attribute from a percentage.
+    ///
+    /// This can also be created [from a ratio](Self::from_ratio).
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use fontique::Stretch;
+    /// assert_eq!(Stretch::from_percentage(87.5), Stretch::SEMI_CONDENSED);
+    /// ```
     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);
+    /// ```
     pub fn ratio(self) -> f32 {
         self.0
     }
@@ -100,22 +137,37 @@ impl Stretch {
         self.0 * 100.0
     }
 
-    /// Returns true if the stretch is normal.
+    /// Returns `true` if the stretch is [normal].
+    ///
+    /// [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]).
+    ///
+    /// [normal]: Stretch::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]).
+    ///
+    /// [normal]: Stretch::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,9 +223,16 @@ impl Default for Stretch {
 
 /// Visual weight class of a font, typically on a scale from 1.0 to 1000.0.
 ///
-/// In variable fonts, this can be controlled with the `wght` axis.
+/// 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>
+///
+/// In CSS, this corresponds to the [`font-weight`] property.
+///
+/// [axis]: crate::AxisInfo
+/// [`font-weight`]: https://www.w3.org/TR/css-fonts-4/#font-weight-prop
 #[derive(Copy, Clone, PartialEq, PartialOrd, Debug)]
 pub struct Weight(f32);
 
@@ -190,7 +249,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 +283,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,10 +334,17 @@ 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.
+/// and `slnt` [axes] for italic and oblique styles, respectively.
 ///
 /// See <https://fonts.google.com/knowledge/glossary/style>
+///
+/// In CSS, this corresponds to the [`font-style`] property.
+///
+/// [axes]: crate::AxisInfo
+/// [`font-style`]: https://www.w3.org/TR/css-fonts-4/#font-style-prop
 #[derive(Copy, Clone, PartialEq, Default, Debug)]
 pub enum Style {
     /// An upright or "roman" style.

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,7 +83,8 @@ 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()
     }

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
@@ -166,6 +171,8 @@ impl Drop for Query<'_> {
 }
 
 /// Determines whether a font query operation will continue.
+///
+/// See [`Query::matches_with`].
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 pub enum QueryStatus {
     /// Query should continue with the next font.
@@ -175,6 +182,9 @@ pub enum QueryStatus {
 }
 
 /// Family descriptor for a font query.
+///
+/// This allows [`Query::set_families`] to
+/// take a variety of family types.
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 pub enum QueryFamily<'a> {
     /// A named font family.
@@ -203,14 +213,14 @@ impl From<GenericFamily> for QueryFamily<'static> {
     }
 }
 
-/// Candidate font generated by a query.
+/// Candidate font generated by a [`Query`].
 #[derive(Clone, Debug)]
 pub struct QueryFont {
     /// Family identifier and index of the font in the family font list.
     pub family: (FamilyId, usize),
     /// Blob containing the font data.
     pub blob: Blob<u8>,
-    /// Index of a font in a font collection (ttc) file.
+    /// Index of a font in a font collection (`ttc`) file.
     pub index: u32,
     /// Synthesis suggestions for this font based on the requested attributes.
     pub synthesis: Synthesis,

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`.
+    /// Always returns `true` when [`locale`](Self::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