diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +## 0.3.3.1 + +- Fixed documentation displaying, which was fucked up almost everywhere. + ## 0.3.3 - Support for linear-1.19. diff --git a/smoothie.cabal b/smoothie.cabal --- a/smoothie.cabal +++ b/smoothie.cabal @@ -1,8 +1,10 @@ name: smoothie -version: 0.3.3 -synopsis: Smooth curves via several splines and polynomials. -description: This package exports several splines and curves you can use - to interpolate points in between. +version: 0.3.3.1 +synopsis: Smooth curves via several interpolation modes +description: This package exports several splines you can use + to interpolate points in between. It includes instances for + so that + you can quickly store the splines and restore them. homepage: https://github.com/phaazon/smoothie license: BSD3 license-file: LICENSE diff --git a/src/Data/Spline.hs b/src/Data/Spline.hs --- a/src/Data/Spline.hs +++ b/src/Data/Spline.hs @@ -7,12 +7,31 @@ -- Stability : experimental -- Portability : portable -- --- A @Spline a s@ represents a curve in which 'a' is very likely to be --- 'Additive' (see "linear") and 's' is the sampling type. +-- This package works around two primary types: +-- +-- - 'Key' +-- - 'Spline' +-- +-- A @'Spline' a s@ represents a curve in which 'a' is very likely to be +-- 'Additive' (see ) and +-- 's' is the sampling type. +-- +-- A 'Key' is used to hold data in a 'Spline'. It adds interpolation mode to +-- data for __each__ 'Key' used to build the 'Spline'. +-- +-- Through the library, you’ll see types like: +-- +-- @ ('Additive' a) => a s @ +-- +-- That is due to the fact some functions work on 'a' as a polymorphic +-- first-class value. That enables more flexibility in the implemantation and +-- the interface. Thus, in most cases, you can any type of your choice as long +-- as it’s an aditive one. ---------------------------------------------------------------------------- module Data.Spline ( - module X + -- * Re-exports + module Data.Spline.Curve ) where -import Data.Spline.Curve as X +import Data.Spline.Curve diff --git a/src/Data/Spline/Curve.hs b/src/Data/Spline/Curve.hs --- a/src/Data/Spline/Curve.hs +++ b/src/Data/Spline/Curve.hs @@ -8,10 +8,13 @@ -- Maintainer : Dimitri Sabadie -- Stability : experimental -- Portability : portable +-- +-- This module defines 'Spline's and related functions. Because a 'Spline' +-- requires 'Key's, the "Data.Spline.Key" module is also exported. ----------------------------------------------------------------------------- module Data.Spline.Curve ( - -- * Spline + -- * Splines Spline , splineKeys , splineSampler @@ -20,26 +23,30 @@ -- * Sampling splines , sample -- * Re-exported - , module X + , module Data.Spline.Key ) where import Control.Monad ( guard ) import Data.Aeson import Data.List ( sortBy ) import Data.Ord ( comparing ) -import Data.Spline.Key as X +import Data.Spline.Key import Data.Vector ( Vector, (!?), fromList ) import Linear ( Additive ) --- |A @Spline@ is a collection of keys with associated interpolation modes. --- Given two keys which indices are /i/ and /i+1/, the interpolation mode on the --- resulting curve is performed using the interpolation mode of the key /i/. +-- |A @'Spline' a s@ is a collection of 'Key's with associated interpolation +-- modes. +-- +-- Given two 'Key's which indices are /i/ and /i+1/, the interpolation mode on +-- the resulting curve is performed using the interpolation mode of the key /i/. -- Thus, the interpolation mode of the latest key might be ignored. There’s an --- exception, though, when using the 'Bezier' interpolation mode. +-- exception, though, when using the 'Bezier' interpolation mode. Feel free +-- to dig in the "Key" documentation. data Spline a s = Spline { - -- |Extract the keys. + -- |Extract the 'Key's. splineKeys :: Vector (Key (a s)) - -- |Extract the sampler. + -- |Extract the sampler. The sampler is a function used to extract a + -- reference value used to perform several operations on the 'Key's. , splineSampler :: a s -> s } @@ -48,12 +55,12 @@ keys <- o .: "keys" pure $ \sampler -> spline sampler keys --- |Build a 'Spline a s'. +-- |Build a @'Spline' a s@. -- --- 'a s' is the type hold by keys. For instance, @V2 Float@. +-- @a s@ is the type held by 'Key's. For instance, @'V2' Float@. -- --- The first argument of the function, which has type @a s -> s@ is a function --- used to extract the sampling value of each keys. In most cases, that value +-- The first argument of the function, which has type @a s -> s@, is a function +-- used to extract the sampling value of each 'Key's. In most cases, that value -- represents the time or the frame of a simulation. That value is used to -- perform sampling comparison. spline :: (Ord s) diff --git a/src/Data/Spline/Key.hs b/src/Data/Spline/Key.hs --- a/src/Data/Spline/Key.hs +++ b/src/Data/Spline/Key.hs @@ -14,7 +14,7 @@ -- * Key type Key(..) , keyValue - -- * interpolation + -- * Interpolation , interpolateKeys , normalizeSampling ) where @@ -26,17 +26,17 @@ -- for instance, left and right handles for a 'Bezier' curve, or whatever the -- interpolation might need. -- --- @Hold v@ is used to express no interpolation and holds its latest value until --- the next key. +-- @H'old' v@ is used to express no interpolation and holds its latest value +-- until the next key. -- --- @Linear v@ represents a linear interpolation until the next key. +-- @'Linear' v@ represents a linear interpolation until the next key. -- --- @Cosine v@ represents a cosine interpolation until the next key. +-- @'Cosine' v@ represents a cosine interpolation until the next key. -- --- @CubicHermite v@ represents a cubic hermitian interpolation until the next +-- @'CubicHermite' v@ represents a cubic hermitian interpolation until the next -- key. -- --- @Bezier l v r@ represents a cubic Bezier interpolation, where 'l' refers +-- @'Bezier' l v r@ represents a cubic 'Bezier' interpolation, where 'l' refers -- to the input – left – tangent of the key and 'r' is the -- output – right – tangent of the key. data Key a @@ -79,13 +79,14 @@ CubicHermite a -> a Bezier _ a _ -> a --- |@interpolateKeys t start end@ interpolates between 'start' and 'end' using +-- |@'interpolateKeys' t start end@ interpolates between 'start' and 'end' using -- 's' as a normalized sampling value. -- -- Satisfies the following laws: +-- -- @ --- interpolateKeys 0 start _ = start --- interpolateKeys 1 _ end = end +-- 'interpolateKeys' 0 start _ = start +-- 'interpolateKeys' 1 _ end = end -- @ interpolateKeys :: (Additive a,Floating s) => s -> Key (a s) -> Key (a s) -> a s interpolateKeys s start end = case start of @@ -99,8 +100,8 @@ where b = keyValue end --- @interpolateBezier s k0 r0 l1 k1@ performs a Bezier interpolation --- between keys 'k0' and 'k1' using their respectives right and left tangents. +-- @'interpolateBezier' s k0 r0 l1 k1@ performs a 'Bezier' interpolation +-- between keys 'k0' and 'k1' using their respective right and left tangents. interpolateBezier :: (Additive a,Floating s) => s -> a s @@ -113,15 +114,15 @@ u = k0 ^+^ (r0 ^-^ k0) ^* s v = l1 ^+^ (k1 ^-^ l1) ^* s --- |Normalize a sampling value by clamping and scaling it between two keys. +-- |Normalize a sampling value by clamping and scaling it between two 'Key's. -- -- The following laws should be satisfied in order to get a coherent output: -- -- @ -- sampler :: a s -> s -- --- sampler (keyValue k1) <= s >= sampler (keyValue k0) --- 0 <= normalizeSampling sampler s k0 k1 <= 1 +-- sampler ('keyValue' k1) <= s >= sampler ('keyValue' k0) +-- 0 <= 'normalizeSampling' sampler s k0 k1 <= 1 -- @ normalizeSampling :: (Fractional s) => (a s -> s)