Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fontique: Improve docs #97

Merged
merged 1 commit into from
Aug 19, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .clippy.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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", ".."]
3 changes: 3 additions & 0 deletions fontique/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ rust-version.workspace = true
license.workspace = true
repository.workspace = true

[package.metadata.docs.rs]
all-features = true

[lints]
workspace = true

Expand Down
98 changes: 87 additions & 11 deletions fontique/src/attributes.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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);

Expand All @@ -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.
Expand All @@ -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
}
Expand All @@ -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 {
Expand Down Expand Up @@ -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);

Expand All @@ -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.
Expand Down Expand Up @@ -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> {
waywardmonkeys marked this conversation as resolved.
Show resolved Hide resolved
let s = s.trim();
Some(match s {
Expand Down Expand Up @@ -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.
Expand Down
17 changes: 13 additions & 4 deletions fontique/src/collection/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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,
}

Expand All @@ -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),
Expand All @@ -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()
}
Expand Down
14 changes: 12 additions & 2 deletions fontique/src/collection/query.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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,
Expand Down
16 changes: 11 additions & 5 deletions fontique/src/fallback.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down
Loading